From 6051ea7eb0c2097677c40d2312e513ee23e5610b Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Tue, 6 Dec 2022 18:11:31 +0100 Subject: [PATCH 0001/1444] Update source file testnet.md --- docs/understand-stacks/testnet.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/understand-stacks/testnet.md b/docs/understand-stacks/testnet.md index 045265bad0..5c46eab6e9 100644 --- a/docs/understand-stacks/testnet.md +++ b/docs/understand-stacks/testnet.md @@ -6,14 +6,14 @@ sidebar_position: 2 ## About testnet -The testnet is a separate blockchain from the Stacks mainnet analogous to a staging environnment. It's a network used by developers to test their apps, smart contracts, or changes to the protocol in a production-like environment. +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. +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) @@ -31,4 +31,4 @@ The hosted Stacks Blockchain API for the testnet is available at this base URL: https://stacks-node-api.testnet.stacks.co/ ``` -![](/img/api_testnet_status.png) \ No newline at end of file +![](/img/api_testnet_status.png) From f372192dc4bbf0e0f9ec00f8e1a04fbc9fd147df Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Tue, 6 Dec 2022 18:11:32 +0100 Subject: [PATCH 0002/1444] Update source file language-functions.md --- .../clarity-language/language-functions.md | 13 +++---------- 1 file changed, 3 insertions(+), 10 deletions(-) diff --git a/docs/write-smart-contracts/clarity-language/language-functions.md b/docs/write-smart-contracts/clarity-language/language-functions.md index 2dc30c65db..624f32f86e 100644 --- a/docs/write-smart-contracts/clarity-language/language-functions.md +++ b/docs/write-smart-contracts/clarity-language/language-functions.md @@ -159,12 +159,6 @@ Returns the integer remainder from integer dividing `i1` by `i2`. In the event o #### 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. -Note: Corner cases are handled with the following rules: - * if both `i1` and `i2` are `0`, return `1` - * if `i1` is `1`, return `1` - * if `i1` is `0`, return `0` - * if `i2` is `1`, return `i1` - * if `i2` is negative or greater than `u32::MAX`, throw a runtime error #### example: ```clarity (pow 2 3) ;; Returns 8 @@ -382,7 +376,7 @@ Applicable sequence types are `(list A)`, `buff`, `string-ascii` and `string-utf ### as-max-len? #### input: `sequence_A, uint` -#### output: `(optional sequence_A)` +#### 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. @@ -715,8 +709,7 @@ The `secp256k1-recover?` function recovers the public key used to sign the messa 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. -The function throws an unchecked error if the buffers have a wrong length. +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 @@ -1607,4 +1600,4 @@ definition (i.e., you cannot put such a statement in the middle of a function bo (ok u0)) (define-public (transfer? (from principal) (to principal) (amount uint)) (ok u0)) -``` +``` \ No newline at end of file From ad0e5ebbecbaeef769fe67cd5211b235a7af44f8 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Tue, 6 Dec 2022 18:12:05 +0100 Subject: [PATCH 0003/1444] New translations language-functions.md (French) --- .../clarity-language/language-functions.md | 13 +++++++++---- 1 file changed, 9 insertions(+), 4 deletions(-) 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 index a6011cca8b..c7708995b6 100644 --- 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 @@ -158,7 +158,12 @@ Returns the integer remainder from integer dividing `i1` by `i2`. In the event o #### 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. +Returns the result of raising `i1` to the power of `i2`. In the event of an _overflow_, throws a runtime error. Note: Corner cases are handled with the following rules: + * if both `i1` and `i2` are `0`, return `1` + * if `i1` is `1`, return `1` + * if `i1` is `0`, return `0` + * if `i2` is `1`, return `i1` + * if `i2` is negative or greater than `u32::MAX`, throw a runtime error #### example: ```clarity (pow 2 3) ;; Returns 8 @@ -349,7 +354,7 @@ The `func` argument must be a literal function name. Applicable sequence types a ### as-max-len? #### input: `sequence_A, uint` -#### output: `sequence_A` +#### output: `(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. 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)`. ` @@ -628,7 +633,7 @@ The `secp256k1-recover?` function recovers the public key used to sign the messa #### 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. +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. The function throws an unchecked error if the buffers have a wrong length. #### example: ```clarity (secp256k1-verify 0xde5b9eb9e7c5592930eb2e30a01369c36586d872082ed8181ee83d2a0ec20f04 @@ -1385,4 +1390,4 @@ Like other kinds of definition statements, `impl-trait` may only be used at the ```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 +``` From 76f41d17ed2f8ec06ff8047f614493ab85f4e1a0 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Tue, 6 Dec 2022 18:12:08 +0100 Subject: [PATCH 0004/1444] New translations language-functions.md (Spanish) --- .../clarity-language/language-functions.md | 13 +++++++++---- 1 file changed, 9 insertions(+), 4 deletions(-) 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 index 8fb14ca8f2..ff52036e70 100644 --- 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 @@ -158,7 +158,12 @@ Returns the integer remainder from integer dividing `i1` by `i2`. In the event o #### 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. +Returns the result of raising `i1` to the power of `i2`. In the event of an _overflow_, throws a runtime error. Note: Corner cases are handled with the following rules: + * if both `i1` and `i2` are `0`, return `1` + * if `i1` is `1`, return `1` + * if `i1` is `0`, return `0` + * if `i2` is `1`, return `i1` + * if `i2` is negative or greater than `u32::MAX`, throw a runtime error #### ejemplo: ```clarity (pow 2 3) ;; Returns 8 @@ -349,7 +354,7 @@ The `func` argument must be a literal function name. Applicable sequence types a ### as-max-len? #### input: `sequence_A, uint` -#### output: `sequence_A` +#### output: `(optional 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)`. ` @@ -628,7 +633,7 @@ The `secp256k1-recover?` function recovers the public key used to sign the messa #### 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. +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. The function throws an unchecked error if the buffers have a wrong length. #### ejemplo: ```clarity (secp256k1-verify 0xde5b9eb9e7c5592930eb2e30a01369c36586d872082ed8181ee83d2a0ec20f04 @@ -1384,4 +1389,4 @@ Like other kinds of definition statements, `impl-trait` may only be used at the (ok u0)) (define-public (transfer? (from principal) (to principal) (amount uint)) (ok u0)) -``` \ No newline at end of file +``` From 499f3181870e73bf430043615a64685a76c58847 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Tue, 6 Dec 2022 18:12:10 +0100 Subject: [PATCH 0005/1444] New translations language-functions.md (German) --- .../clarity-language/language-functions.md | 13 +++++++++---- 1 file changed, 9 insertions(+), 4 deletions(-) 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 index 45be763e21..c650b3ef10 100644 --- 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 @@ -158,7 +158,12 @@ Returns the integer remainder from integer dividing `i1` by `i2`. In the event o #### 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. +Returns the result of raising `i1` to the power of `i2`. In the event of an _overflow_, throws a runtime error. Note: Corner cases are handled with the following rules: + * if both `i1` and `i2` are `0`, return `1` + * if `i1` is `1`, return `1` + * if `i1` is `0`, return `0` + * if `i2` is `1`, return `i1` + * if `i2` is negative or greater than `u32::MAX`, throw a runtime error #### example: ```clarity (pow 2 3) ;; Returns 8 @@ -349,7 +354,7 @@ The `func` argument must be a literal function name. Applicable sequence types a ### as-max-len? #### input: `sequence_A, uint` -#### output: `sequence_A` +#### output: `(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. 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)`. ` @@ -628,7 +633,7 @@ The `secp256k1-recover?` function recovers the public key used to sign the messa #### 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. +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. The function throws an unchecked error if the buffers have a wrong length. #### example: ```clarity (secp256k1-verify 0xde5b9eb9e7c5592930eb2e30a01369c36586d872082ed8181ee83d2a0ec20f04 @@ -1385,4 +1390,4 @@ Like other kinds of definition statements, `impl-trait` may only be used at the ```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 +``` From 0a79353dc2e2a75e8969ec77449d47dd52a6cf4b Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Tue, 6 Dec 2022 18:12:12 +0100 Subject: [PATCH 0006/1444] New translations language-functions.md (Japanese) --- .../clarity-language/language-functions.md | 13 +++++++++---- 1 file changed, 9 insertions(+), 4 deletions(-) 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 index a6011cca8b..c7708995b6 100644 --- 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 @@ -158,7 +158,12 @@ Returns the integer remainder from integer dividing `i1` by `i2`. In the event o #### 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. +Returns the result of raising `i1` to the power of `i2`. In the event of an _overflow_, throws a runtime error. Note: Corner cases are handled with the following rules: + * if both `i1` and `i2` are `0`, return `1` + * if `i1` is `1`, return `1` + * if `i1` is `0`, return `0` + * if `i2` is `1`, return `i1` + * if `i2` is negative or greater than `u32::MAX`, throw a runtime error #### example: ```clarity (pow 2 3) ;; Returns 8 @@ -349,7 +354,7 @@ The `func` argument must be a literal function name. Applicable sequence types a ### as-max-len? #### input: `sequence_A, uint` -#### output: `sequence_A` +#### output: `(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. 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)`. ` @@ -628,7 +633,7 @@ The `secp256k1-recover?` function recovers the public key used to sign the messa #### 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. +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. The function throws an unchecked error if the buffers have a wrong length. #### example: ```clarity (secp256k1-verify 0xde5b9eb9e7c5592930eb2e30a01369c36586d872082ed8181ee83d2a0ec20f04 @@ -1385,4 +1390,4 @@ Like other kinds of definition statements, `impl-trait` may only be used at the ```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 +``` From 4f9625528045b17841749d08d134a34ad64f87d0 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Tue, 6 Dec 2022 18:12:15 +0100 Subject: [PATCH 0007/1444] New translations language-functions.md (Korean) --- .../clarity-language/language-functions.md | 13 +++++++++---- 1 file changed, 9 insertions(+), 4 deletions(-) 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 index a6011cca8b..c7708995b6 100644 --- 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 @@ -158,7 +158,12 @@ Returns the integer remainder from integer dividing `i1` by `i2`. In the event o #### 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. +Returns the result of raising `i1` to the power of `i2`. In the event of an _overflow_, throws a runtime error. Note: Corner cases are handled with the following rules: + * if both `i1` and `i2` are `0`, return `1` + * if `i1` is `1`, return `1` + * if `i1` is `0`, return `0` + * if `i2` is `1`, return `i1` + * if `i2` is negative or greater than `u32::MAX`, throw a runtime error #### example: ```clarity (pow 2 3) ;; Returns 8 @@ -349,7 +354,7 @@ The `func` argument must be a literal function name. Applicable sequence types a ### as-max-len? #### input: `sequence_A, uint` -#### output: `sequence_A` +#### output: `(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. 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)`. ` @@ -628,7 +633,7 @@ The `secp256k1-recover?` function recovers the public key used to sign the messa #### 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. +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. The function throws an unchecked error if the buffers have a wrong length. #### example: ```clarity (secp256k1-verify 0xde5b9eb9e7c5592930eb2e30a01369c36586d872082ed8181ee83d2a0ec20f04 @@ -1385,4 +1390,4 @@ Like other kinds of definition statements, `impl-trait` may only be used at the ```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 +``` From edc820817711a31d5d1ad302cfb689817efd7528 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Tue, 6 Dec 2022 18:12:17 +0100 Subject: [PATCH 0008/1444] New translations language-functions.md (Russian) --- .../clarity-language/language-functions.md | 13 +++++++++---- 1 file changed, 9 insertions(+), 4 deletions(-) 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 index a6011cca8b..c7708995b6 100644 --- 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 @@ -158,7 +158,12 @@ Returns the integer remainder from integer dividing `i1` by `i2`. In the event o #### 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. +Returns the result of raising `i1` to the power of `i2`. In the event of an _overflow_, throws a runtime error. Note: Corner cases are handled with the following rules: + * if both `i1` and `i2` are `0`, return `1` + * if `i1` is `1`, return `1` + * if `i1` is `0`, return `0` + * if `i2` is `1`, return `i1` + * if `i2` is negative or greater than `u32::MAX`, throw a runtime error #### example: ```clarity (pow 2 3) ;; Returns 8 @@ -349,7 +354,7 @@ The `func` argument must be a literal function name. Applicable sequence types a ### as-max-len? #### input: `sequence_A, uint` -#### output: `sequence_A` +#### output: `(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. 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)`. ` @@ -628,7 +633,7 @@ The `secp256k1-recover?` function recovers the public key used to sign the messa #### 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. +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. The function throws an unchecked error if the buffers have a wrong length. #### example: ```clarity (secp256k1-verify 0xde5b9eb9e7c5592930eb2e30a01369c36586d872082ed8181ee83d2a0ec20f04 @@ -1385,4 +1390,4 @@ Like other kinds of definition statements, `impl-trait` may only be used at the ```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 +``` From 0059a14b3f540cf27704c69709fbb553528bcef1 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Tue, 6 Dec 2022 18:12:20 +0100 Subject: [PATCH 0009/1444] New translations language-functions.md (Turkish) --- .../clarity-language/language-functions.md | 13 +++++++++---- 1 file changed, 9 insertions(+), 4 deletions(-) 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 index a6011cca8b..c7708995b6 100644 --- 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 @@ -158,7 +158,12 @@ Returns the integer remainder from integer dividing `i1` by `i2`. In the event o #### 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. +Returns the result of raising `i1` to the power of `i2`. In the event of an _overflow_, throws a runtime error. Note: Corner cases are handled with the following rules: + * if both `i1` and `i2` are `0`, return `1` + * if `i1` is `1`, return `1` + * if `i1` is `0`, return `0` + * if `i2` is `1`, return `i1` + * if `i2` is negative or greater than `u32::MAX`, throw a runtime error #### example: ```clarity (pow 2 3) ;; Returns 8 @@ -349,7 +354,7 @@ The `func` argument must be a literal function name. Applicable sequence types a ### as-max-len? #### input: `sequence_A, uint` -#### output: `sequence_A` +#### output: `(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. 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)`. ` @@ -628,7 +633,7 @@ The `secp256k1-recover?` function recovers the public key used to sign the messa #### 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. +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. The function throws an unchecked error if the buffers have a wrong length. #### example: ```clarity (secp256k1-verify 0xde5b9eb9e7c5592930eb2e30a01369c36586d872082ed8181ee83d2a0ec20f04 @@ -1385,4 +1390,4 @@ Like other kinds of definition statements, `impl-trait` may only be used at the ```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 +``` From 1c123447cf7047faec659dff26c187601a9c4f7a Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Tue, 6 Dec 2022 18:12:22 +0100 Subject: [PATCH 0010/1444] New translations language-functions.md (Chinese Simplified) --- .../clarity-language/language-functions.md | 13 +++++++++---- 1 file changed, 9 insertions(+), 4 deletions(-) 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 index c01d4a2618..2a1fff15ec 100644 --- 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 @@ -158,7 +158,12 @@ Returns the integer remainder from integer dividing `i1` by `i2`. In the event o #### 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. +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. Note: Corner cases are handled with the following rules: + * if both `i1` and `i2` are `0`, return `1` + * if `i1` is `1`, return `1` + * if `i1` is `0`, return `0` + * if `i2` is `1`, return `i1` + * if `i2` is negative or greater than `u32::MAX`, throw a runtime error #### example: ```clarity (pow 2 3) ;; Returns 8 @@ -353,7 +358,7 @@ The `concat` function takes two sequences of the same type, and returns a concat ### as-max-len? #### input: `sequence_A, uint` -#### output: `sequence_A` +#### output: `(optional 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`. ` @@ -634,7 +639,7 @@ The `secp256k1-recover?` function recovers the public key used to sign the messa #### 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. +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. The function throws an unchecked error if the buffers have a wrong length. #### example: ```clarity (secp256k1-verify 0xde5b9eb9e7c5592930eb2e30a01369c36586d872082ed8181ee83d2a0ec20f04 @@ -1390,4 +1395,4 @@ Like other kinds of definition statements, `impl-trait` may only be used at the ```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 +``` From c7484d271cdb6138e2ee5f60fc263fca6501b8a0 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Tue, 6 Dec 2022 18:12:24 +0100 Subject: [PATCH 0011/1444] New translations language-functions.md (Vietnamese) --- .../clarity-language/language-functions.md | 13 +++++++++---- 1 file changed, 9 insertions(+), 4 deletions(-) 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 index 4605b2f4c9..10727f2566 100644 --- 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 @@ -158,7 +158,12 @@ Returns the integer remainder from integer dividing `i1` by `i2`. In the event o #### 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. +Returns the result of raising `i1` to the power of `i2`. In the event of an _overflow_, throws a runtime error. Note: Corner cases are handled with the following rules: + * if both `i1` and `i2` are `0`, return `1` + * if `i1` is `1`, return `1` + * if `i1` is `0`, return `0` + * if `i2` is `1`, return `i1` + * if `i2` is negative or greater than `u32::MAX`, throw a runtime error #### example: ```clarity (pow 2 3) ;; Returns 8 @@ -349,7 +354,7 @@ The `concat` function takes two sequences of the same type, and returns a concat ### as-max-len? #### input: `sequence_A, uint` -#### output: `sequence_A` +#### output: `(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. 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`. ` @@ -628,7 +633,7 @@ The `secp256k1-recover?` function recovers the public key used to sign the messa #### 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. +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. The function throws an unchecked error if the buffers have a wrong length. #### example: ```clarity (secp256k1-verify 0xde5b9eb9e7c5592930eb2e30a01369c36586d872082ed8181ee83d2a0ec20f04 @@ -1382,4 +1387,4 @@ Like other kinds of definition statements, `impl-trait` may only be used at the (ok u0)) (define-public (transfer? (from principal) (to principal) (amount uint)) (ok u0)) -``` \ No newline at end of file +``` From 65cdcdfef7b3dd5b51fff2d9b03f4914a23272bd Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Tue, 6 Dec 2022 18:12:26 +0100 Subject: [PATCH 0012/1444] New translations language-functions.md (Portuguese, Brazilian) --- .../clarity-language/language-functions.md | 13 +++++++++---- 1 file changed, 9 insertions(+), 4 deletions(-) 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 index 2acbb0cc93..8769b753b2 100644 --- 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 @@ -158,7 +158,12 @@ Returns the integer remainder from integer dividing `i1` by `i2`. In the event o #### 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. +Returns the result of raising `i1` to the power of `i2`. In the event of an _overflow_, throws a runtime error. Note: Corner cases are handled with the following rules: + * if both `i1` and `i2` are `0`, return `1` + * if `i1` is `1`, return `1` + * if `i1` is `0`, return `0` + * if `i2` is `1`, return `i1` + * if `i2` is negative or greater than `u32::MAX`, throw a runtime error #### example: ```clarity (pow 2 3) ;; Returns 8 @@ -349,7 +354,7 @@ The `concat` function takes two sequences of the same type, and returns a concat ### as-max-len? #### input: `sequence_A, uint` -#### output: `sequence_A` +#### output: `(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. 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`. ` @@ -628,7 +633,7 @@ The `secp256k1-recover?` function recovers the public key used to sign the messa #### 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. +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. The function throws an unchecked error if the buffers have a wrong length. #### example: ```clarity (secp256k1-verify 0xde5b9eb9e7c5592930eb2e30a01369c36586d872082ed8181ee83d2a0ec20f04 @@ -1379,4 +1384,4 @@ Like other kinds of definition statements, `impl-trait` may only be used at the ```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 +``` From a4db2afcf54d7b6cab05ee7404ee517ae3d2c1ab Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Tue, 6 Dec 2022 18:12:28 +0100 Subject: [PATCH 0013/1444] New translations language-functions.md (Indonesian) --- .../clarity-language/language-functions.md | 13 +++++++++---- 1 file changed, 9 insertions(+), 4 deletions(-) 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 index 6528bfaac9..6a49a293fd 100644 --- 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 @@ -158,7 +158,12 @@ Returns the integer remainder from integer dividing `i1` by `i2`. In the event o #### 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. +Returns the result of raising `i1` to the power of `i2`. In the event of an _overflow_, throws a runtime error. Note: Corner cases are handled with the following rules: + * if both `i1` and `i2` are `0`, return `1` + * if `i1` is `1`, return `1` + * if `i1` is `0`, return `0` + * if `i2` is `1`, return `i1` + * if `i2` is negative or greater than `u32::MAX`, throw a runtime error #### example: ```clarity (pow 2 3) ;; Returns 8 @@ -349,7 +354,7 @@ The `concat` function takes two sequences of the same type, and returns a concat ### as-max-len? #### input: `sequence_A, uint` -#### output: `sequence_A` +#### output: `(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. 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`. ` @@ -628,7 +633,7 @@ The `secp256k1-recover?` function recovers the public key used to sign the messa #### 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. +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. The function throws an unchecked error if the buffers have a wrong length. #### example: ```clarity (secp256k1-verify 0xde5b9eb9e7c5592930eb2e30a01369c36586d872082ed8181ee83d2a0ec20f04 @@ -1382,4 +1387,4 @@ Like other kinds of definition statements, `impl-trait` may only be used at the (ok u0)) (define-public (transfer? (from principal) (to principal) (amount uint)) (ok u0)) -``` \ No newline at end of file +``` From bdf8cf2d9db7206f14a55aecc0e8be37b1ff875d Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Tue, 6 Dec 2022 18:12:30 +0100 Subject: [PATCH 0014/1444] New translations language-functions.md (Hindi) --- .../clarity-language/language-functions.md | 13 +++++++++---- 1 file changed, 9 insertions(+), 4 deletions(-) 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 index 4605b2f4c9..10727f2566 100644 --- 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 @@ -158,7 +158,12 @@ Returns the integer remainder from integer dividing `i1` by `i2`. In the event o #### 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. +Returns the result of raising `i1` to the power of `i2`. In the event of an _overflow_, throws a runtime error. Note: Corner cases are handled with the following rules: + * if both `i1` and `i2` are `0`, return `1` + * if `i1` is `1`, return `1` + * if `i1` is `0`, return `0` + * if `i2` is `1`, return `i1` + * if `i2` is negative or greater than `u32::MAX`, throw a runtime error #### example: ```clarity (pow 2 3) ;; Returns 8 @@ -349,7 +354,7 @@ The `concat` function takes two sequences of the same type, and returns a concat ### as-max-len? #### input: `sequence_A, uint` -#### output: `sequence_A` +#### output: `(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. 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`. ` @@ -628,7 +633,7 @@ The `secp256k1-recover?` function recovers the public key used to sign the messa #### 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. +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. The function throws an unchecked error if the buffers have a wrong length. #### example: ```clarity (secp256k1-verify 0xde5b9eb9e7c5592930eb2e30a01369c36586d872082ed8181ee83d2a0ec20f04 @@ -1382,4 +1387,4 @@ Like other kinds of definition statements, `impl-trait` may only be used at the (ok u0)) (define-public (transfer? (from principal) (to principal) (amount uint)) (ok u0)) -``` \ No newline at end of file +``` From dc5fc70bc7e49ea9e827880d5eddda2826a55c66 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Tue, 6 Dec 2022 18:12:31 +0100 Subject: [PATCH 0015/1444] New translations testnet.md (French) --- .../current/understand-stacks/testnet.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) 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 index 59934a5bde..ba6dee45a9 100644 --- a/i18n/fr/docusaurus-plugin-content-docs/current/understand-stacks/testnet.md +++ b/i18n/fr/docusaurus-plugin-content-docs/current/understand-stacks/testnet.md @@ -6,7 +6,7 @@ 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. +The testnet is a separate blockchain from the Stacks mainnet analogous to a staging environnment. 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 @@ -30,4 +30,4 @@ The hosted Stacks Blockchain API for the testnet is available at this base URL: https://stacks-node-api.testnet.stacks.co/ ``` -![](/img/api_testnet_status.png) +![](/img/api_testnet_status.png) \ No newline at end of file From 5ba379ebb1fe540071abc66c720f00adfeb11820 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Tue, 6 Dec 2022 18:12:32 +0100 Subject: [PATCH 0016/1444] New translations testnet.md (Spanish) --- .../current/understand-stacks/testnet.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) 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 index d4e4fb8259..5573920f9e 100644 --- a/i18n/es/docusaurus-plugin-content-docs/current/understand-stacks/testnet.md +++ b/i18n/es/docusaurus-plugin-content-docs/current/understand-stacks/testnet.md @@ -6,7 +6,7 @@ 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. +The testnet is a separate blockchain from the Stacks mainnet analogous to a staging environnment. 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 @@ -30,4 +30,4 @@ La API Stacks Blockchain para la red de pruebas testnet está disponible en esta https://stacks-node-api.testnet.stacks.co/ ``` -![](/img/api_testnet_status.png) +![](/img/api_testnet_status.png) \ No newline at end of file From 7afabaa28040e2faf049ec7d1b5dd22341613ffe Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Tue, 6 Dec 2022 18:12:34 +0100 Subject: [PATCH 0017/1444] New translations testnet.md (German) --- .../current/understand-stacks/testnet.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) 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 index 59934a5bde..ba6dee45a9 100644 --- a/i18n/de/docusaurus-plugin-content-docs/current/understand-stacks/testnet.md +++ b/i18n/de/docusaurus-plugin-content-docs/current/understand-stacks/testnet.md @@ -6,7 +6,7 @@ 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. +The testnet is a separate blockchain from the Stacks mainnet analogous to a staging environnment. 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 @@ -30,4 +30,4 @@ The hosted Stacks Blockchain API for the testnet is available at this base URL: https://stacks-node-api.testnet.stacks.co/ ``` -![](/img/api_testnet_status.png) +![](/img/api_testnet_status.png) \ No newline at end of file From c8c17e567e2b30b2af190aa2fe407e776aed5cbf Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Tue, 6 Dec 2022 18:12:35 +0100 Subject: [PATCH 0018/1444] New translations testnet.md (Japanese) --- .../current/understand-stacks/testnet.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) 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 index 59934a5bde..ba6dee45a9 100644 --- a/i18n/ja/docusaurus-plugin-content-docs/current/understand-stacks/testnet.md +++ b/i18n/ja/docusaurus-plugin-content-docs/current/understand-stacks/testnet.md @@ -6,7 +6,7 @@ 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. +The testnet is a separate blockchain from the Stacks mainnet analogous to a staging environnment. 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 @@ -30,4 +30,4 @@ The hosted Stacks Blockchain API for the testnet is available at this base URL: https://stacks-node-api.testnet.stacks.co/ ``` -![](/img/api_testnet_status.png) +![](/img/api_testnet_status.png) \ No newline at end of file From 646148fb517c27103cd213bd57417d08cfb7e866 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Tue, 6 Dec 2022 18:12:36 +0100 Subject: [PATCH 0019/1444] New translations testnet.md (Korean) --- .../current/understand-stacks/testnet.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) 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 index 59934a5bde..ba6dee45a9 100644 --- a/i18n/ko/docusaurus-plugin-content-docs/current/understand-stacks/testnet.md +++ b/i18n/ko/docusaurus-plugin-content-docs/current/understand-stacks/testnet.md @@ -6,7 +6,7 @@ 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. +The testnet is a separate blockchain from the Stacks mainnet analogous to a staging environnment. 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 @@ -30,4 +30,4 @@ The hosted Stacks Blockchain API for the testnet is available at this base URL: https://stacks-node-api.testnet.stacks.co/ ``` -![](/img/api_testnet_status.png) +![](/img/api_testnet_status.png) \ No newline at end of file From 3a5ba60e7ea1c70282667e578caeef192b5a91a8 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Tue, 6 Dec 2022 18:12:37 +0100 Subject: [PATCH 0020/1444] New translations testnet.md (Russian) --- .../current/understand-stacks/testnet.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) 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 index 59934a5bde..ba6dee45a9 100644 --- a/i18n/ru/docusaurus-plugin-content-docs/current/understand-stacks/testnet.md +++ b/i18n/ru/docusaurus-plugin-content-docs/current/understand-stacks/testnet.md @@ -6,7 +6,7 @@ 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. +The testnet is a separate blockchain from the Stacks mainnet analogous to a staging environnment. 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 @@ -30,4 +30,4 @@ The hosted Stacks Blockchain API for the testnet is available at this base URL: https://stacks-node-api.testnet.stacks.co/ ``` -![](/img/api_testnet_status.png) +![](/img/api_testnet_status.png) \ No newline at end of file From db975e750676f567984bc0282701bc7c3bd907bf Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Tue, 6 Dec 2022 18:12:38 +0100 Subject: [PATCH 0021/1444] New translations testnet.md (Turkish) --- .../current/understand-stacks/testnet.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) 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 index 59934a5bde..ba6dee45a9 100644 --- a/i18n/tr/docusaurus-plugin-content-docs/current/understand-stacks/testnet.md +++ b/i18n/tr/docusaurus-plugin-content-docs/current/understand-stacks/testnet.md @@ -6,7 +6,7 @@ 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. +The testnet is a separate blockchain from the Stacks mainnet analogous to a staging environnment. 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 @@ -30,4 +30,4 @@ The hosted Stacks Blockchain API for the testnet is available at this base URL: https://stacks-node-api.testnet.stacks.co/ ``` -![](/img/api_testnet_status.png) +![](/img/api_testnet_status.png) \ No newline at end of file From a8650efcf6a91ff10176be28d8c31bc2c78d3cc8 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Tue, 6 Dec 2022 18:12:39 +0100 Subject: [PATCH 0022/1444] New translations testnet.md (Chinese Simplified) --- .../current/understand-stacks/testnet.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) 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 index 35a30f9673..a48fe58598 100644 --- a/i18n/zh/docusaurus-plugin-content-docs/current/understand-stacks/testnet.md +++ b/i18n/zh/docusaurus-plugin-content-docs/current/understand-stacks/testnet.md @@ -6,7 +6,7 @@ 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. +The testnet is a separate blockchain from the Stacks mainnet analogous to a staging environnment. 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 @@ -30,4 +30,4 @@ The hosted Stacks Blockchain API for the testnet is available at this base URL: https://stacks-node-api.testnet.stacks.co/ ``` -![](/img/api_testnet_status.png) +![](/img/api_testnet_status.png) \ No newline at end of file From 4dbc30e976e4dc14a528d9821a7bb0a0205780ab Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Tue, 6 Dec 2022 18:12:40 +0100 Subject: [PATCH 0023/1444] New translations testnet.md (Vietnamese) --- .../current/understand-stacks/testnet.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) 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 index 59934a5bde..ba6dee45a9 100644 --- a/i18n/vi/docusaurus-plugin-content-docs/current/understand-stacks/testnet.md +++ b/i18n/vi/docusaurus-plugin-content-docs/current/understand-stacks/testnet.md @@ -6,7 +6,7 @@ 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. +The testnet is a separate blockchain from the Stacks mainnet analogous to a staging environnment. 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 @@ -30,4 +30,4 @@ The hosted Stacks Blockchain API for the testnet is available at this base URL: https://stacks-node-api.testnet.stacks.co/ ``` -![](/img/api_testnet_status.png) +![](/img/api_testnet_status.png) \ No newline at end of file From 60fbaa39e6be5b9c8d75d5ac98cbd954c2e6b275 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Tue, 6 Dec 2022 18:12:42 +0100 Subject: [PATCH 0024/1444] New translations testnet.md (Portuguese, Brazilian) --- .../current/understand-stacks/testnet.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) 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 index 4fb78f9c06..b20bd11031 100644 --- a/i18n/pt/docusaurus-plugin-content-docs/current/understand-stacks/testnet.md +++ b/i18n/pt/docusaurus-plugin-content-docs/current/understand-stacks/testnet.md @@ -6,7 +6,7 @@ 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. +The testnet is a separate blockchain from the Stacks mainnet analogous to a staging environnment. 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 @@ -29,4 +29,4 @@ The hosted Stacks Blockchain API for the testnet is available at this base URL: https://stacks-node-api.testnet.stacks.co/ ``` -![](/img/api_testnet_status.png) +![](/img/api_testnet_status.png) \ No newline at end of file From bbb6fc4a9af283e4e0a6dd8277a4f6d3b5fb8c8a Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Tue, 6 Dec 2022 18:12:43 +0100 Subject: [PATCH 0025/1444] New translations testnet.md (Indonesian) --- .../current/understand-stacks/testnet.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) 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 index f130802d8b..b4b6041be9 100644 --- a/i18n/id/docusaurus-plugin-content-docs/current/understand-stacks/testnet.md +++ b/i18n/id/docusaurus-plugin-content-docs/current/understand-stacks/testnet.md @@ -6,7 +6,7 @@ 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. +The testnet is a separate blockchain from the Stacks mainnet analogous to a staging environnment. 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 @@ -30,4 +30,4 @@ The hosted Stacks Blockchain API for the testnet is available at this base URL: https://stacks-node-api.testnet.stacks.co/ ``` -![](/img/api_testnet_status.png) +![](/img/api_testnet_status.png) \ No newline at end of file From 98e06c661bc0852a1d4a56c943140931a6b1e070 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Tue, 6 Dec 2022 18:12:44 +0100 Subject: [PATCH 0026/1444] New translations testnet.md (Hindi) --- .../current/understand-stacks/testnet.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) 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 index 59934a5bde..ba6dee45a9 100644 --- a/i18n/hi/docusaurus-plugin-content-docs/current/understand-stacks/testnet.md +++ b/i18n/hi/docusaurus-plugin-content-docs/current/understand-stacks/testnet.md @@ -6,7 +6,7 @@ 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. +The testnet is a separate blockchain from the Stacks mainnet analogous to a staging environnment. 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 @@ -30,4 +30,4 @@ The hosted Stacks Blockchain API for the testnet is available at this base URL: https://stacks-node-api.testnet.stacks.co/ ``` -![](/img/api_testnet_status.png) +![](/img/api_testnet_status.png) \ No newline at end of file From eec21e0828d9b2ec6460ab765fe9b0a420a94280 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Tue, 3 Jan 2023 21:13:19 +0100 Subject: [PATCH 0027/1444] Update source file testnet.md --- docs/understand-stacks/testnet.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/understand-stacks/testnet.md b/docs/understand-stacks/testnet.md index 5c46eab6e9..045265bad0 100644 --- a/docs/understand-stacks/testnet.md +++ b/docs/understand-stacks/testnet.md @@ -6,14 +6,14 @@ 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. +The testnet is a separate blockchain from the Stacks mainnet analogous to a staging environnment. 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. +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) @@ -31,4 +31,4 @@ The hosted Stacks Blockchain API for the testnet is available at this base URL: https://stacks-node-api.testnet.stacks.co/ ``` -![](/img/api_testnet_status.png) +![](/img/api_testnet_status.png) \ No newline at end of file From 6664e963bf6ffe6c25e5880a7ba69a3ae3642582 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Tue, 3 Jan 2023 21:13:20 +0100 Subject: [PATCH 0028/1444] Update source file language-functions.md --- .../clarity-language/language-functions.md | 13 ++++++++++--- 1 file changed, 10 insertions(+), 3 deletions(-) diff --git a/docs/write-smart-contracts/clarity-language/language-functions.md b/docs/write-smart-contracts/clarity-language/language-functions.md index 624f32f86e..2dc30c65db 100644 --- a/docs/write-smart-contracts/clarity-language/language-functions.md +++ b/docs/write-smart-contracts/clarity-language/language-functions.md @@ -159,6 +159,12 @@ Returns the integer remainder from integer dividing `i1` by `i2`. In the event o #### 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. +Note: Corner cases are handled with the following rules: + * if both `i1` and `i2` are `0`, return `1` + * if `i1` is `1`, return `1` + * if `i1` is `0`, return `0` + * if `i2` is `1`, return `i1` + * if `i2` is negative or greater than `u32::MAX`, throw a runtime error #### example: ```clarity (pow 2 3) ;; Returns 8 @@ -376,7 +382,7 @@ Applicable sequence types are `(list A)`, `buff`, `string-ascii` and `string-utf ### as-max-len? #### input: `sequence_A, uint` -#### output: `sequence_A` +#### output: `(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. @@ -709,7 +715,8 @@ The `secp256k1-recover?` function recovers the public key used to sign the messa 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. +The signature includes 64 bytes plus an optional additional recovery id (00..03) for a total of 64 or 65 bytes. +The function throws an unchecked error if the buffers have a wrong length. #### example: ```clarity (secp256k1-verify 0xde5b9eb9e7c5592930eb2e30a01369c36586d872082ed8181ee83d2a0ec20f04 @@ -1600,4 +1607,4 @@ definition (i.e., you cannot put such a statement in the middle of a function bo (ok u0)) (define-public (transfer? (from principal) (to principal) (amount uint)) (ok u0)) -``` \ No newline at end of file +``` From 33394905422e4788ef425c57204bcc68509c6c92 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Tue, 3 Jan 2023 21:13:27 +0100 Subject: [PATCH 0029/1444] New translations index.md (Spanish) --- .../current/blockchain/index.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/i18n/es/docusaurus-plugin-content-docs/current/blockchain/index.md b/i18n/es/docusaurus-plugin-content-docs/current/blockchain/index.md index 13db24ec30..27701d8d7a 100644 --- a/i18n/es/docusaurus-plugin-content-docs/current/blockchain/index.md +++ b/i18n/es/docusaurus-plugin-content-docs/current/blockchain/index.md @@ -1,10 +1,10 @@ --- title: Blockchain -description: Stacks Blockchain +description: Blockchain de Stacks sidebar_position: 6 --- -Below is a guide to start working locally with the Stacks Blockchain. +A continuación hay una guía para empezar a trabajar localmente con la Blockchain de Stacks. Code repository is [here](https://github.com/stacks-network/stacks-blockchain). From 4b6d5d3faed9e2c1ab9e5bfa80815984bee2d2eb Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Tue, 3 Jan 2023 23:49:53 +0100 Subject: [PATCH 0030/1444] New translations index.md (Spanish) --- .../current/blockchain/index.md | 22 +++++++++---------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/i18n/es/docusaurus-plugin-content-docs/current/blockchain/index.md b/i18n/es/docusaurus-plugin-content-docs/current/blockchain/index.md index 27701d8d7a..c9ecad8bd4 100644 --- a/i18n/es/docusaurus-plugin-content-docs/current/blockchain/index.md +++ b/i18n/es/docusaurus-plugin-content-docs/current/blockchain/index.md @@ -6,23 +6,23 @@ sidebar_position: 6 A continuación hay una guía para empezar a trabajar localmente con la Blockchain de Stacks. -Code repository is [here](https://github.com/stacks-network/stacks-blockchain). +El código está alojado en este [repositorio de Github](https://github.com/stacks-network/stacks-blockchain). -## Getting started with the Stacks Blockchain +## Empezando con la Blockchain de Stacks -### Download and build stacks-blockchain +### Descargar y compilar la blockchain de Stacks -The first step is to ensure that you have Rust and the support software installed. +El primer paso es asegurarse de que tiene Rust y el software de soporte instalado. ```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/ +Para compilar en Windows, sigue las instrucciones del instalador de rustup en https://rustup.rs/ ::: -From there, you can clone the Stacks Blockchain repository: +Desde allí, puede clonar el repositorio de la Blockchain de Stacks: ```bash git clone --depth=1 https://github.com/stacks-network/stacks-blockchain.git @@ -30,21 +30,21 @@ git clone --depth=1 https://github.com/stacks-network/stacks-blockchain.git cd stacks-blockchain ``` -Then build the project: +Luego compile el proyecto: ```bash cargo build ``` -Run the tests: +Ejecuta las pruebas: ```bash cargo test testnet -- --test-threads=1 ``` -### Encode and sign transactions +### Codificar y firmar transacciones -Here, we have generated a keypair that will be used for signing the upcoming transactions: +Aquí, hemos generado un par de claves que se utilizará para firmar las próximas transacciones: ```bash cargo run --bin blockstack-cli generate-sk --testnet @@ -57,7 +57,7 @@ cargo run --bin blockstack-cli generate-sk --testnet # } ``` -This keypair is already registered in the `testnet-follower-conf.toml` file, so it can be used as presented here. +Este par de claves ya está registrado en el archivo `testnet-follower-conf.toml`, por lo que puede ser usado como se presenta aquí. We will interact with the following simple contract `kv-store`. In our examples, we will assume this contract is saved to `./kv-store.clar`: From d8d1e517cd1efa6e1f0968c1671e151839d4ecb0 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Tue, 10 Jan 2023 04:25:54 +0100 Subject: [PATCH 0031/1444] Update source file glossary.md --- docs/references/glossary.md | 136 +++++++++++++++++++++--------------- 1 file changed, 80 insertions(+), 56 deletions(-) diff --git a/docs/references/glossary.md b/docs/references/glossary.md index 921584ddd3..7253959dc7 100644 --- a/docs/references/glossary.md +++ b/docs/references/glossary.md @@ -5,18 +5,21 @@ 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. +Sharing this address allows anyone to send Bitcoin to the address. -#### Block +#### 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 +#### 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) @@ -33,105 +36,117 @@ Looks like a bitcoin address but starts with `ID` for example: #### 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 +#### 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. +"The rules governing the creation of new valid records in a blockchain database and the mining algorithms used for this purpose. -#### Control plane +#### 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 +#### core node A server that runs Stacks Blockchain services. -#### Crypto asset +#### 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 +#### 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) +#### 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 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 +#### 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 +#### 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) +#### 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 +#### ephemeral key A cryptographic key is called ephemeral if it is generated for each execution of a key establishment process. -#### Fork +#### 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 +#### genesis block The genesis block is the first block of the Stacks blockchain, which will create the initial 1.32 billion Stacks Tokens. -#### (Digital) Identity -A way to represent a collection of activities in the digital world that are controlled by one or more persons, representatives of an organization or in general an entity, for example a software program. On the Stacks network, an identity is represented by a Stacks address and can have an associated unique name (see BNS) and a public profile. +#### 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. +#### 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. +#### 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 +#### light clients Clients that can independently validate the existence of transactions by downloading only block headers and not the entire blockchain. -#### Mesh network +#### 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 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 +#### 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 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 +#### 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 +#### 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 key -Private keys matches a corresponding public key. A public key also looks like a string of letters and numbers: +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 +#### 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 (PoW) +#### 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 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. @@ -139,25 +154,28 @@ The exact format of the public and private key depend on the software you use to #### Public Key Infrastructure (PKI) A system which returns a cryptographic public key associated with a name. -#### Replicated state machines (RSMs) +#### 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 Key -A different word for "Seed phrase". +#### 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 one or more identities on the Stacks blockchain and Bitcoin blockchain. The seed phrase consists of 24 words in a sequence. Both the word *and its position in 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`. +#### seed phrase -#### Smart contract +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 +#### 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 a 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*. " + 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. @@ -172,26 +190,32 @@ A complete version of our open-source software available on Github at https://gi 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 associated with a public key. +#### storage hub +A Gaia instance run by a hub provider or software. A Gaia hub stores data in a separate, addressed location. -#### Storage provider +#### storage provider A third-party company cloud or software provider that hosts one or more Gaia storage hubs. -#### Transaction +#### transaction A transaction is a unit of work within a block. -#### Transaction fee -Fees paid by participants of a blockchain to miners for their work to process transactions. +#### transaction fee +Fees paid by participants in a transaction to miners. -#### Two-sided market problem +#### 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. -#### 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 Stack network. +#### 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 ability. You can view only balances and transaction history. +#### 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. From 2145cc7d7de7828bcbd2e8332e02775a0252d238 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Tue, 10 Jan 2023 04:25:55 +0100 Subject: [PATCH 0032/1444] Update source file nft.md --- docs/services-using-stacks/nft.md | 8 -------- 1 file changed, 8 deletions(-) diff --git a/docs/services-using-stacks/nft.md b/docs/services-using-stacks/nft.md index abb770663c..bfa0505dc9 100644 --- a/docs/services-using-stacks/nft.md +++ b/docs/services-using-stacks/nft.md @@ -21,18 +21,10 @@ Please edit this page to add any relevant new site that we are missing. ![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) \ No newline at end of file From 7bf73be4811a2b3c248509c1f679cfe611d89eb2 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Tue, 10 Jan 2023 04:26:16 +0100 Subject: [PATCH 0033/1444] New translations glossary.md (French) --- .../current/references/glossary.md | 130 ++++++++---------- 1 file changed, 55 insertions(+), 75 deletions(-) diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/references/glossary.md b/i18n/fr/docusaurus-plugin-content-docs/current/references/glossary.md index f97908371a..3ea755ab54 100644 --- a/i18n/fr/docusaurus-plugin-content-docs/current/references/glossary.md +++ b/i18n/fr/docusaurus-plugin-content-docs/current/references/glossary.md @@ -5,19 +5,16 @@ 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. +A string of letters and numbers. `3E53XjqK4Cxt71BGeP2VhpcotM8LZ853C8` Sharing this address allows anyone to send Bitcoin to the address. -#### block +#### 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 +#### Blochain 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) @@ -33,138 +30,127 @@ Looks like a bitcoin address but starts with `ID` for example: `ID-1J3PUxY5uDShU #### 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 +#### 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. +The rules governing the creation of new valid records in a blockchain database and the mining algorithms used for this purpose. -#### control plane +#### 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 +#### Core node A server that runs Stacks Blockchain services. -#### crypto-asset +#### 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 +#### 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) +#### 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 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 +#### 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 +#### 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) +#### 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 +#### Ephemeral key A cryptographic key is called ephemeral if it is generated for each execution of a key establishment process. -#### fork +#### 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 +#### 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. +#### (Digital) Identity +A way to represent a collection of activities in the digital world that are controlled by one or more persons, representatives of an organization or in general an entity, for example a software program. On the Stacks network, an identity is represented by a Stacks address and can have an associated unique name (see BNS) and a public profile. -#### 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". +#### 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. +#### 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. -#### light clients +#### 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 +#### 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 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 +#### 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 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 +#### 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 +#### 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 key -Private keys matches a corresponding public key. A public key also looks like a string of letters and numbers: +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 +#### 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 +#### Proof of work (PoW) 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 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) +#### 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` +#### Secret Key +A different word for "Seed phrase". -#### seed phrase +#### Seed phrase +Used to access one or more identities on the Stacks blockchain and Bitcoin blockchain. The seed phrase consists of 24 words in a sequence. Both the word *and its position in 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`. -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 +#### 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 +#### 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*. " + 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 a 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. @@ -178,32 +164,26 @@ A complete version of our open-source software available on Github at https://gi #### 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 hub +A Gaia instance run by a hub provider or software. A Gaia hub stores data in a separate, addressed location associated with a public key. -#### storage provider +#### Storage provider A third-party company cloud or software provider that hosts one or more Gaia storage hubs. -#### transaction +#### Transaction A transaction is a unit of work within a block. -#### transaction fee -Fees paid by participants in a transaction to miners. +#### Transaction fee +Fees paid by participants of a blockchain to miners for their work to process transactions. -#### two-sided market problem +#### 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. +#### 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 Stack network. -#### watch-only wallet -A wallet without send and receive ability. You can view only balances and transaction history. +#### Watch-only wallet +A wallet without send 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. From 369f8b9d23198493f1f9e3c49e1a644a0f94ce87 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Tue, 10 Jan 2023 04:26:19 +0100 Subject: [PATCH 0034/1444] New translations nft.md (French) --- .../current/services-using-stacks/nft.md | 8 ++++++++ 1 file changed, 8 insertions(+) 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 index bfa0505dc9..abb770663c 100644 --- 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 @@ -21,10 +21,18 @@ Please edit this page to add any relevant new site that we are missing. ![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) \ No newline at end of file From 3cdcb63307314c1202234a7cbee06fad9863aa35 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Tue, 10 Jan 2023 04:26:20 +0100 Subject: [PATCH 0035/1444] New translations glossary.md (Spanish) --- .../current/references/glossary.md | 130 ++++++++---------- 1 file changed, 55 insertions(+), 75 deletions(-) diff --git a/i18n/es/docusaurus-plugin-content-docs/current/references/glossary.md b/i18n/es/docusaurus-plugin-content-docs/current/references/glossary.md index 0099a439aa..9908acdef7 100644 --- a/i18n/es/docusaurus-plugin-content-docs/current/references/glossary.md +++ b/i18n/es/docusaurus-plugin-content-docs/current/references/glossary.md @@ -5,19 +5,16 @@ 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. +A string of letters and numbers. `3E53XjqK4Cxt71BGeP2VhpcotM8LZ853C8` Sharing this address allows anyone to send Bitcoin to the address. -#### bloque +#### 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 +#### 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) @@ -33,138 +30,127 @@ Looks like a bitcoin address but starts with `ID` for example: `ID-1J3PUxY5uDShU #### 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 +#### 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. +The rules governing the creation of new valid records in a blockchain database and the mining algorithms used for this purpose. -#### control plane +#### 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 +#### Core node A server that runs Stacks Blockchain services. -#### crypto-asset +#### 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 +#### 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) +#### 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 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 +#### 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 +#### 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) +#### 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 +#### Ephemeral key A cryptographic key is called ephemeral if it is generated for each execution of a key establishment process. -#### fork +#### 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 +#### 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" - -#### 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. +#### (Digital) Identity +A way to represent a collection of activities in the digital world that are controlled by one or more persons, representatives of an organization or in general an entity, for example a software program. On the Stacks network, an identity is represented by a Stacks address and can have an associated unique name (see BNS) and a public profile. -#### 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". +#### 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. +#### 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. -#### light clients +#### 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 +#### 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. -#### minería +#### 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 +#### 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 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 +#### 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 +#### 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 key -Private keys matches a corresponding public key. A public key also looks like a string of letters and numbers: +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 +#### 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 +#### Proof of work (PoW) 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 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) +#### 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` +#### Secret Key +A different word for "Seed phrase". -#### Frase semilla +#### Seed phrase +Used to access one or more identities on the Stacks blockchain and Bitcoin blockchain. The seed phrase consists of 24 words in a sequence. Both the word *and its position in 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`. -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 +#### 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 +#### 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*. " + 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 a 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. @@ -178,32 +164,26 @@ A complete version of our open-source software available on Github at https://gi #### 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 hub +A Gaia instance run by a hub provider or software. A Gaia hub stores data in a separate, addressed location associated with a public key. -#### storage provider +#### Storage provider A third-party company cloud or software provider that hosts one or more Gaia storage hubs. -#### transacción +#### Transaction A transaction is a unit of work within a block. -#### transaction fee -Fees paid by participants in a transaction to miners. +#### Transaction fee +Fees paid by participants of a blockchain to miners for their work to process transactions. -#### two-sided market problem +#### 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. +#### 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 Stack network. -#### watch-only wallet -A wallet without send and receive ability. You can view only balances and transaction history. +#### Watch-only wallet +A wallet without send 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. From bea4ac20bf1acb2928f0375d46e1588b6a596d25 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Tue, 10 Jan 2023 04:26:23 +0100 Subject: [PATCH 0036/1444] New translations nft.md (Spanish) --- .../current/services-using-stacks/nft.md | 10 +++++++++- 1 file changed, 9 insertions(+), 1 deletion(-) 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 index d24c66ba1e..5851befe48 100644 --- 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 @@ -21,9 +21,17 @@ Por favor edita esta página para agregar cualquier sitio web relevante que falt ![captura de pantalla de página web](/img/sh_nft_megapont.png) +### [Satoshibles](https://satoshibles.com/) + +![captura de pantalla de página web](/img/sh_nft_satoshibles.png) + ### [StacksArt](https://www.stacksart.com/) -![captura de pantalla de página web](/img/sh_nft_stacksart.png) +![website-screenshot](/img/sh_nft_stacksart.png) + +### [StacksBridge](https://stacksbridge.com/) + +![website-screenshot](/img/sh_nft_stacksbridge.png) ### [Superfandom](https://superfandom.io/) From 14c9e9ef8b32c0b8f3d50664c38126f255402f2b Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Tue, 10 Jan 2023 04:26:24 +0100 Subject: [PATCH 0037/1444] New translations glossary.md (German) --- .../current/references/glossary.md | 130 ++++++++---------- 1 file changed, 55 insertions(+), 75 deletions(-) diff --git a/i18n/de/docusaurus-plugin-content-docs/current/references/glossary.md b/i18n/de/docusaurus-plugin-content-docs/current/references/glossary.md index ebb24ca97b..5453fc9a41 100644 --- a/i18n/de/docusaurus-plugin-content-docs/current/references/glossary.md +++ b/i18n/de/docusaurus-plugin-content-docs/current/references/glossary.md @@ -5,19 +5,16 @@ 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. +A string of letters and numbers. `3E53XjqK4Cxt71BGeP2VhpcotM8LZ853C8` Sharing this address allows anyone to send Bitcoin to the address. -#### block +#### 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 +#### 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) @@ -33,138 +30,127 @@ Looks like a bitcoin address but starts with `ID` for example: `ID-1J3PUxY5uDShU #### 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 +#### 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. +The rules governing the creation of new valid records in a blockchain database and the mining algorithms used for this purpose. -#### control plane +#### 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 +#### Core node A server that runs Stacks Blockchain services. -#### crypto-asset +#### 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 +#### 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) +#### 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 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 +#### 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 +#### 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) +#### 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 +#### Ephemeral key A cryptographic key is called ephemeral if it is generated for each execution of a key establishment process. -#### fork +#### 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 +#### 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. +#### (Digital) Identity +A way to represent a collection of activities in the digital world that are controlled by one or more persons, representatives of an organization or in general an entity, for example a software program. On the Stacks network, an identity is represented by a Stacks address and can have an associated unique name (see BNS) and a public profile. -#### 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". +#### 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. +#### 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. -#### light clients +#### 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 +#### 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 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 +#### 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 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 +#### 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 +#### 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 key -Private keys matches a corresponding public key. A public key also looks like a string of letters and numbers: +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 +#### 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 +#### Proof of work (PoW) 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 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) +#### 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` +#### Secret Key +A different word for "Seed phrase". -#### seed phrase +#### Seed phrase +Used to access one or more identities on the Stacks blockchain and Bitcoin blockchain. The seed phrase consists of 24 words in a sequence. Both the word *and its position in 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`. -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 +#### 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 +#### 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*. " + 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 a 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. @@ -178,32 +164,26 @@ A complete version of our open-source software available on Github at https://gi #### 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 hub +A Gaia instance run by a hub provider or software. A Gaia hub stores data in a separate, addressed location associated with a public key. -#### storage provider +#### Storage provider A third-party company cloud or software provider that hosts one or more Gaia storage hubs. -#### transaction +#### Transaction A transaction is a unit of work within a block. -#### transaction fee -Fees paid by participants in a transaction to miners. +#### Transaction fee +Fees paid by participants of a blockchain to miners for their work to process transactions. -#### two-sided market problem +#### 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. +#### 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 Stack network. -#### watch-only wallet -A wallet without send and receive ability. You can view only balances and transaction history. +#### Watch-only wallet +A wallet without send 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. From dd779222e55bf21de8fbd063bba07a4b5a4fac19 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Tue, 10 Jan 2023 04:26:26 +0100 Subject: [PATCH 0038/1444] New translations nft.md (German) --- .../current/services-using-stacks/nft.md | 8 ++++++++ 1 file changed, 8 insertions(+) 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 index bfa0505dc9..abb770663c 100644 --- 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 @@ -21,10 +21,18 @@ Please edit this page to add any relevant new site that we are missing. ![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) \ No newline at end of file From 9e7aae84cce2dfb7d7a0548605c23ac45111c041 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Tue, 10 Jan 2023 04:26:28 +0100 Subject: [PATCH 0039/1444] New translations glossary.md (Japanese) --- .../current/references/glossary.md | 130 ++++++++---------- 1 file changed, 55 insertions(+), 75 deletions(-) diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/references/glossary.md b/i18n/ja/docusaurus-plugin-content-docs/current/references/glossary.md index 23badef6ac..3f00855d16 100644 --- a/i18n/ja/docusaurus-plugin-content-docs/current/references/glossary.md +++ b/i18n/ja/docusaurus-plugin-content-docs/current/references/glossary.md @@ -5,19 +5,16 @@ 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. +A string of letters and numbers. `3E53XjqK4Cxt71BGeP2VhpcotM8LZ853C8` Sharing this address allows anyone to send Bitcoin to the address. -#### block +#### 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 +#### 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) @@ -33,138 +30,127 @@ Looks like a bitcoin address but starts with `ID` for example: `ID-1J3PUxY5uDShU #### 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 +#### 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. +The rules governing the creation of new valid records in a blockchain database and the mining algorithms used for this purpose. -#### control plane +#### 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 +#### Core node A server that runs Stacks Blockchain services. -#### crypto-asset +#### 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 +#### 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) +#### 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 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 +#### 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 +#### 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) +#### 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 +#### Ephemeral key A cryptographic key is called ephemeral if it is generated for each execution of a key establishment process. -#### fork +#### 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 +#### 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. +#### (Digital) Identity +A way to represent a collection of activities in the digital world that are controlled by one or more persons, representatives of an organization or in general an entity, for example a software program. On the Stacks network, an identity is represented by a Stacks address and can have an associated unique name (see BNS) and a public profile. -#### 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". +#### 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. +#### 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. -#### light clients +#### 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 +#### 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 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 +#### 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 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 +#### 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 +#### 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 key -Private keys matches a corresponding public key. A public key also looks like a string of letters and numbers: +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 +#### 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 +#### Proof of work (PoW) 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 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) +#### 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` +#### Secret Key +A different word for "Seed phrase". -#### seed phrase +#### Seed phrase +Used to access one or more identities on the Stacks blockchain and Bitcoin blockchain. The seed phrase consists of 24 words in a sequence. Both the word *and its position in 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`. -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 +#### 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 +#### 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*. " + 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 a 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. @@ -178,32 +164,26 @@ A complete version of our open-source software available on Github at https://gi #### 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 hub +A Gaia instance run by a hub provider or software. A Gaia hub stores data in a separate, addressed location associated with a public key. -#### storage provider +#### Storage provider A third-party company cloud or software provider that hosts one or more Gaia storage hubs. -#### transaction +#### Transaction A transaction is a unit of work within a block. -#### transaction fee -Fees paid by participants in a transaction to miners. +#### Transaction fee +Fees paid by participants of a blockchain to miners for their work to process transactions. -#### two-sided market problem +#### 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. +#### 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 Stack network. -#### watch-only wallet -A wallet without send and receive ability. You can view only balances and transaction history. +#### Watch-only wallet +A wallet without send 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. From 4c64b4998664e3dd10e68466548320730971c094 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Tue, 10 Jan 2023 04:26:30 +0100 Subject: [PATCH 0040/1444] New translations nft.md (Japanese) --- .../current/services-using-stacks/nft.md | 8 ++++++++ 1 file changed, 8 insertions(+) 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 index bfa0505dc9..abb770663c 100644 --- 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 @@ -21,10 +21,18 @@ Please edit this page to add any relevant new site that we are missing. ![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) \ No newline at end of file From 4b4b15429a8a61771f80e76af2abd3c7003829fa Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Tue, 10 Jan 2023 04:26:32 +0100 Subject: [PATCH 0041/1444] New translations glossary.md (Korean) --- .../current/references/glossary.md | 130 ++++++++---------- 1 file changed, 55 insertions(+), 75 deletions(-) diff --git a/i18n/ko/docusaurus-plugin-content-docs/current/references/glossary.md b/i18n/ko/docusaurus-plugin-content-docs/current/references/glossary.md index f97908371a..488fbee9b2 100644 --- a/i18n/ko/docusaurus-plugin-content-docs/current/references/glossary.md +++ b/i18n/ko/docusaurus-plugin-content-docs/current/references/glossary.md @@ -5,19 +5,16 @@ 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. +A string of letters and numbers. `3E53XjqK4Cxt71BGeP2VhpcotM8LZ853C8` Sharing this address allows anyone to send Bitcoin to the address. -#### block +#### 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 +#### 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) @@ -33,138 +30,127 @@ Looks like a bitcoin address but starts with `ID` for example: `ID-1J3PUxY5uDShU #### 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 +#### 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. +The rules governing the creation of new valid records in a blockchain database and the mining algorithms used for this purpose. -#### control plane +#### 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 +#### Core node A server that runs Stacks Blockchain services. -#### crypto-asset +#### 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 +#### 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) +#### 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 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 +#### 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 +#### 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) +#### 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 +#### Ephemeral key A cryptographic key is called ephemeral if it is generated for each execution of a key establishment process. -#### fork +#### 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 +#### 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. +#### (Digital) Identity +A way to represent a collection of activities in the digital world that are controlled by one or more persons, representatives of an organization or in general an entity, for example a software program. On the Stacks network, an identity is represented by a Stacks address and can have an associated unique name (see BNS) and a public profile. -#### 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". +#### 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. +#### 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. -#### light clients +#### 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 +#### 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 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 +#### 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 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 +#### 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 +#### 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 key -Private keys matches a corresponding public key. A public key also looks like a string of letters and numbers: +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 +#### 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 +#### Proof of work (PoW) 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 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) +#### 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` +#### Secret Key +A different word for "Seed phrase". -#### seed phrase +#### Seed phrase +Used to access one or more identities on the Stacks blockchain and Bitcoin blockchain. The seed phrase consists of 24 words in a sequence. Both the word *and its position in 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`. -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 +#### 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 +#### 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*. " + 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 a 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. @@ -178,32 +164,26 @@ A complete version of our open-source software available on Github at https://gi #### 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 hub +A Gaia instance run by a hub provider or software. A Gaia hub stores data in a separate, addressed location associated with a public key. -#### storage provider +#### Storage provider A third-party company cloud or software provider that hosts one or more Gaia storage hubs. -#### transaction +#### Transaction A transaction is a unit of work within a block. -#### transaction fee -Fees paid by participants in a transaction to miners. +#### Transaction fee +Fees paid by participants of a blockchain to miners for their work to process transactions. -#### two-sided market problem +#### 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. +#### 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 Stack network. -#### watch-only wallet -A wallet without send and receive ability. You can view only balances and transaction history. +#### Watch-only wallet +A wallet without send 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. From 8fae1428e3048f64adb208da334958f32ffa0a98 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Tue, 10 Jan 2023 04:26:34 +0100 Subject: [PATCH 0042/1444] New translations nft.md (Korean) --- .../current/services-using-stacks/nft.md | 8 ++++++++ 1 file changed, 8 insertions(+) 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 index bfa0505dc9..abb770663c 100644 --- 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 @@ -21,10 +21,18 @@ Please edit this page to add any relevant new site that we are missing. ![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) \ No newline at end of file From cab49ed141e453943ae387fd0391ec8245fc17de Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Tue, 10 Jan 2023 04:26:36 +0100 Subject: [PATCH 0043/1444] New translations glossary.md (Russian) --- .../current/references/glossary.md | 130 ++++++++---------- 1 file changed, 55 insertions(+), 75 deletions(-) diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/references/glossary.md b/i18n/ru/docusaurus-plugin-content-docs/current/references/glossary.md index f97908371a..488fbee9b2 100644 --- a/i18n/ru/docusaurus-plugin-content-docs/current/references/glossary.md +++ b/i18n/ru/docusaurus-plugin-content-docs/current/references/glossary.md @@ -5,19 +5,16 @@ 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. +A string of letters and numbers. `3E53XjqK4Cxt71BGeP2VhpcotM8LZ853C8` Sharing this address allows anyone to send Bitcoin to the address. -#### block +#### 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 +#### 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) @@ -33,138 +30,127 @@ Looks like a bitcoin address but starts with `ID` for example: `ID-1J3PUxY5uDShU #### 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 +#### 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. +The rules governing the creation of new valid records in a blockchain database and the mining algorithms used for this purpose. -#### control plane +#### 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 +#### Core node A server that runs Stacks Blockchain services. -#### crypto-asset +#### 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 +#### 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) +#### 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 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 +#### 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 +#### 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) +#### 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 +#### Ephemeral key A cryptographic key is called ephemeral if it is generated for each execution of a key establishment process. -#### fork +#### 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 +#### 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. +#### (Digital) Identity +A way to represent a collection of activities in the digital world that are controlled by one or more persons, representatives of an organization or in general an entity, for example a software program. On the Stacks network, an identity is represented by a Stacks address and can have an associated unique name (see BNS) and a public profile. -#### 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". +#### 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. +#### 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. -#### light clients +#### 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 +#### 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 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 +#### 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 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 +#### 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 +#### 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 key -Private keys matches a corresponding public key. A public key also looks like a string of letters and numbers: +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 +#### 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 +#### Proof of work (PoW) 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 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) +#### 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` +#### Secret Key +A different word for "Seed phrase". -#### seed phrase +#### Seed phrase +Used to access one or more identities on the Stacks blockchain and Bitcoin blockchain. The seed phrase consists of 24 words in a sequence. Both the word *and its position in 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`. -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 +#### 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 +#### 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*. " + 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 a 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. @@ -178,32 +164,26 @@ A complete version of our open-source software available on Github at https://gi #### 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 hub +A Gaia instance run by a hub provider or software. A Gaia hub stores data in a separate, addressed location associated with a public key. -#### storage provider +#### Storage provider A third-party company cloud or software provider that hosts one or more Gaia storage hubs. -#### transaction +#### Transaction A transaction is a unit of work within a block. -#### transaction fee -Fees paid by participants in a transaction to miners. +#### Transaction fee +Fees paid by participants of a blockchain to miners for their work to process transactions. -#### two-sided market problem +#### 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. +#### 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 Stack network. -#### watch-only wallet -A wallet without send and receive ability. You can view only balances and transaction history. +#### Watch-only wallet +A wallet without send 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. From 4f5374bcb072d00cd8bb4d43e1f017e1d327e4f1 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Tue, 10 Jan 2023 04:26:38 +0100 Subject: [PATCH 0044/1444] New translations nft.md (Russian) --- .../current/services-using-stacks/nft.md | 8 ++++++++ 1 file changed, 8 insertions(+) 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 index bfa0505dc9..abb770663c 100644 --- 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 @@ -21,10 +21,18 @@ Please edit this page to add any relevant new site that we are missing. ![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) \ No newline at end of file From c25617311ddd032f021c8d3ccb91782a1374e78d Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Tue, 10 Jan 2023 04:26:40 +0100 Subject: [PATCH 0045/1444] New translations glossary.md (Turkish) --- .../current/references/glossary.md | 130 ++++++++---------- 1 file changed, 55 insertions(+), 75 deletions(-) diff --git a/i18n/tr/docusaurus-plugin-content-docs/current/references/glossary.md b/i18n/tr/docusaurus-plugin-content-docs/current/references/glossary.md index f97908371a..488fbee9b2 100644 --- a/i18n/tr/docusaurus-plugin-content-docs/current/references/glossary.md +++ b/i18n/tr/docusaurus-plugin-content-docs/current/references/glossary.md @@ -5,19 +5,16 @@ 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. +A string of letters and numbers. `3E53XjqK4Cxt71BGeP2VhpcotM8LZ853C8` Sharing this address allows anyone to send Bitcoin to the address. -#### block +#### 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 +#### 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) @@ -33,138 +30,127 @@ Looks like a bitcoin address but starts with `ID` for example: `ID-1J3PUxY5uDShU #### 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 +#### 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. +The rules governing the creation of new valid records in a blockchain database and the mining algorithms used for this purpose. -#### control plane +#### 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 +#### Core node A server that runs Stacks Blockchain services. -#### crypto-asset +#### 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 +#### 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) +#### 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 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 +#### 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 +#### 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) +#### 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 +#### Ephemeral key A cryptographic key is called ephemeral if it is generated for each execution of a key establishment process. -#### fork +#### 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 +#### 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. +#### (Digital) Identity +A way to represent a collection of activities in the digital world that are controlled by one or more persons, representatives of an organization or in general an entity, for example a software program. On the Stacks network, an identity is represented by a Stacks address and can have an associated unique name (see BNS) and a public profile. -#### 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". +#### 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. +#### 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. -#### light clients +#### 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 +#### 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 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 +#### 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 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 +#### 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 +#### 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 key -Private keys matches a corresponding public key. A public key also looks like a string of letters and numbers: +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 +#### 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 +#### Proof of work (PoW) 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 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) +#### 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` +#### Secret Key +A different word for "Seed phrase". -#### seed phrase +#### Seed phrase +Used to access one or more identities on the Stacks blockchain and Bitcoin blockchain. The seed phrase consists of 24 words in a sequence. Both the word *and its position in 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`. -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 +#### 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 +#### 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*. " + 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 a 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. @@ -178,32 +164,26 @@ A complete version of our open-source software available on Github at https://gi #### 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 hub +A Gaia instance run by a hub provider or software. A Gaia hub stores data in a separate, addressed location associated with a public key. -#### storage provider +#### Storage provider A third-party company cloud or software provider that hosts one or more Gaia storage hubs. -#### transaction +#### Transaction A transaction is a unit of work within a block. -#### transaction fee -Fees paid by participants in a transaction to miners. +#### Transaction fee +Fees paid by participants of a blockchain to miners for their work to process transactions. -#### two-sided market problem +#### 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. +#### 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 Stack network. -#### watch-only wallet -A wallet without send and receive ability. You can view only balances and transaction history. +#### Watch-only wallet +A wallet without send 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. From abc574a560acdaef01cf789eee98a99c5ccca0dd Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Tue, 10 Jan 2023 04:26:42 +0100 Subject: [PATCH 0046/1444] New translations nft.md (Turkish) --- .../current/services-using-stacks/nft.md | 8 ++++++++ 1 file changed, 8 insertions(+) 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 index bfa0505dc9..abb770663c 100644 --- 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 @@ -21,10 +21,18 @@ Please edit this page to add any relevant new site that we are missing. ![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) \ No newline at end of file From 86bc1069ee1e88d1ce0ddf6ea8f33a72392132d7 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Tue, 10 Jan 2023 04:26:44 +0100 Subject: [PATCH 0047/1444] New translations glossary.md (Chinese Simplified) --- .../current/references/glossary.md | 130 ++++++++---------- 1 file changed, 55 insertions(+), 75 deletions(-) diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/references/glossary.md b/i18n/zh/docusaurus-plugin-content-docs/current/references/glossary.md index b315c60d84..9857303579 100644 --- a/i18n/zh/docusaurus-plugin-content-docs/current/references/glossary.md +++ b/i18n/zh/docusaurus-plugin-content-docs/current/references/glossary.md @@ -5,19 +5,16 @@ 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. +A string of letters and numbers. `3E53XjqK4Cxt71BGeP2VhpcotM8LZ853C8` Sharing this address allows anyone to send Bitcoin to the address. -#### block +#### 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 +#### 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) @@ -33,138 +30,127 @@ Looks like a bitcoin address but starts with `ID` for example: `ID-1J3PUxY5uDShU #### 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 +#### 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. +The rules governing the creation of new valid records in a blockchain database and the mining algorithms used for this purpose. -#### control plane +#### 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 +#### Core node A server that runs Stacks Blockchain services. -#### crypto-asset +#### 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 +#### 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) +#### 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 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. -#### digital fingerprint +#### 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 +#### 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) +#### 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 +#### Ephemeral key A cryptographic key is called ephemeral if it is generated for each execution of a key establishment process. -#### fork +#### 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 +#### 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. +#### (Digital) Identity +A way to represent a collection of activities in the digital world that are controlled by one or more persons, representatives of an organization or in general an entity, for example a software program. On the Stacks network, an identity is represented by a Stacks address and can have an associated unique name (see BNS) and a public profile. -#### 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". +#### 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. +#### Know your customer (KYC) +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. -#### light clients +#### 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 +#### 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 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 +#### 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 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 +#### 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 +#### 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 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: +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 +#### 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 +#### Proof of work (PoW) 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 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) +#### 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` +#### Secret Key +A different word for "Seed phrase". -#### seed phrase +#### Seed phrase +Used to access one or more identities on the Stacks blockchain and Bitcoin blockchain. The seed phrase consists of 24 words in a sequence. Both the word *and its position in 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`. -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 +#### 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 +#### 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*. " + 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 a 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. @@ -178,32 +164,26 @@ A complete version of our open-source software available on Github at https://gi #### 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 hub +A Gaia instance run by a hub provider or software. A Gaia hub stores data in a separate, addressed location associated with a public key. -#### storage provider +#### Storage provider A third-party company cloud or software provider that hosts one or more Gaia storage hubs. -#### transaction +#### Transaction A transaction is a unit of work within a block. -#### transaction fee -Fees paid by participants in a transaction to miners. +#### Transaction fee +Fees paid by participants of a blockchain to miners for their work to process transactions. -#### two-sided market problem +#### 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. +#### 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. Wallet addresses are therefore used to assign the ownership of digital assets on the Stack 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. +#### Watch-only wallet +A wallet without send 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. From 26d086a41a38b5997775367cc63957c8f7bb4d1a Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Tue, 10 Jan 2023 04:26:46 +0100 Subject: [PATCH 0048/1444] New translations nft.md (Chinese Simplified) --- .../current/services-using-stacks/nft.md | 8 ++++++++ 1 file changed, 8 insertions(+) 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 index 6f1f8ecfa0..c228a773d5 100644 --- 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 @@ -21,10 +21,18 @@ Please edit this page to add any relevant new site that we are missing. ![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) \ No newline at end of file From c801fed3b949dd1d8e2093a74a9fb7d28358a2af Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Tue, 10 Jan 2023 04:26:48 +0100 Subject: [PATCH 0049/1444] New translations glossary.md (Vietnamese) --- .../current/references/glossary.md | 130 ++++++++---------- 1 file changed, 55 insertions(+), 75 deletions(-) diff --git a/i18n/vi/docusaurus-plugin-content-docs/current/references/glossary.md b/i18n/vi/docusaurus-plugin-content-docs/current/references/glossary.md index 1027a52c96..20474763a7 100644 --- a/i18n/vi/docusaurus-plugin-content-docs/current/references/glossary.md +++ b/i18n/vi/docusaurus-plugin-content-docs/current/references/glossary.md @@ -5,19 +5,16 @@ 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. +A string of letters and numbers. `3E53XjqK4Cxt71BGeP2VhpcotM8LZ853C8` Sharing this address allows anyone to send Bitcoin to the address. -#### block +#### 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 +#### 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) @@ -33,138 +30,127 @@ Looks like a bitcoin address but starts with `ID` for example: `ID-1J3PUxY5uDShU #### 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 +#### 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. +The rules governing the creation of new valid records in a blockchain database and the mining algorithms used for this purpose. -#### control plane +#### 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 +#### Core node A server that runs Stacks Blockchain services. -#### crypto-asset +#### 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 +#### 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) +#### 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 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 +#### 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 +#### 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) +#### 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 +#### Ephemeral key A cryptographic key is called ephemeral if it is generated for each execution of a key establishment process. -#### fork +#### 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 +#### 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. +#### (Digital) Identity +A way to represent a collection of activities in the digital world that are controlled by one or more persons, representatives of an organization or in general an entity, for example a software program. On the Stacks network, an identity is represented by a Stacks address and can have an associated unique name (see BNS) and a public profile. -#### 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". +#### 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. +#### 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. -#### light clients +#### 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 +#### 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 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 +#### 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 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 +#### 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 +#### 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 key -Private keys matches a corresponding public key. A public key also looks like a string of letters and numbers: +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 +#### 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 +#### Proof of work (PoW) 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 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) +#### 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` +#### Secret Key +A different word for "Seed phrase". -#### seed phrase +#### Seed phrase +Used to access one or more identities on the Stacks blockchain and Bitcoin blockchain. The seed phrase consists of 24 words in a sequence. Both the word *and its position in 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`. -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 +#### 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 +#### 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*. " + 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 a 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. @@ -178,32 +164,26 @@ A complete version of our open-source software available on Github at https://gi #### 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 hub +A Gaia instance run by a hub provider or software. A Gaia hub stores data in a separate, addressed location associated with a public key. -#### storage provider +#### Storage provider A third-party company cloud or software provider that hosts one or more Gaia storage hubs. -#### transaction +#### Transaction A transaction is a unit of work within a block. -#### transaction fee -Fees paid by participants in a transaction to miners. +#### Transaction fee +Fees paid by participants of a blockchain to miners for their work to process transactions. -#### two-sided market problem +#### 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. +#### 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 Stack network. -#### watch-only wallet -A wallet without send and receive ability. You can view only balances and transaction history. +#### Watch-only wallet +A wallet without send 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. From 4ea377fa38cb38d7c1f32b04caa475d526f8ba95 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Tue, 10 Jan 2023 04:26:50 +0100 Subject: [PATCH 0050/1444] New translations nft.md (Vietnamese) --- .../current/services-using-stacks/nft.md | 8 ++++++++ 1 file changed, 8 insertions(+) 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 index bfa0505dc9..abb770663c 100644 --- 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 @@ -21,10 +21,18 @@ Please edit this page to add any relevant new site that we are missing. ![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) \ No newline at end of file From ff49c6afe8661f3dccee7e30ff89a6917e383f5e Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Tue, 10 Jan 2023 04:26:51 +0100 Subject: [PATCH 0051/1444] New translations glossary.md (Portuguese, Brazilian) --- .../current/references/glossary.md | 130 ++++++++---------- 1 file changed, 55 insertions(+), 75 deletions(-) diff --git a/i18n/pt/docusaurus-plugin-content-docs/current/references/glossary.md b/i18n/pt/docusaurus-plugin-content-docs/current/references/glossary.md index f97908371a..488fbee9b2 100644 --- a/i18n/pt/docusaurus-plugin-content-docs/current/references/glossary.md +++ b/i18n/pt/docusaurus-plugin-content-docs/current/references/glossary.md @@ -5,19 +5,16 @@ 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. +A string of letters and numbers. `3E53XjqK4Cxt71BGeP2VhpcotM8LZ853C8` Sharing this address allows anyone to send Bitcoin to the address. -#### block +#### 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 +#### 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) @@ -33,138 +30,127 @@ Looks like a bitcoin address but starts with `ID` for example: `ID-1J3PUxY5uDShU #### 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 +#### 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. +The rules governing the creation of new valid records in a blockchain database and the mining algorithms used for this purpose. -#### control plane +#### 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 +#### Core node A server that runs Stacks Blockchain services. -#### crypto-asset +#### 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 +#### 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) +#### 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 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 +#### 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 +#### 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) +#### 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 +#### Ephemeral key A cryptographic key is called ephemeral if it is generated for each execution of a key establishment process. -#### fork +#### 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 +#### 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. +#### (Digital) Identity +A way to represent a collection of activities in the digital world that are controlled by one or more persons, representatives of an organization or in general an entity, for example a software program. On the Stacks network, an identity is represented by a Stacks address and can have an associated unique name (see BNS) and a public profile. -#### 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". +#### 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. +#### 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. -#### light clients +#### 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 +#### 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 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 +#### 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 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 +#### 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 +#### 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 key -Private keys matches a corresponding public key. A public key also looks like a string of letters and numbers: +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 +#### 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 +#### Proof of work (PoW) 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 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) +#### 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` +#### Secret Key +A different word for "Seed phrase". -#### seed phrase +#### Seed phrase +Used to access one or more identities on the Stacks blockchain and Bitcoin blockchain. The seed phrase consists of 24 words in a sequence. Both the word *and its position in 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`. -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 +#### 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 +#### 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*. " + 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 a 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. @@ -178,32 +164,26 @@ A complete version of our open-source software available on Github at https://gi #### 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 hub +A Gaia instance run by a hub provider or software. A Gaia hub stores data in a separate, addressed location associated with a public key. -#### storage provider +#### Storage provider A third-party company cloud or software provider that hosts one or more Gaia storage hubs. -#### transaction +#### Transaction A transaction is a unit of work within a block. -#### transaction fee -Fees paid by participants in a transaction to miners. +#### Transaction fee +Fees paid by participants of a blockchain to miners for their work to process transactions. -#### two-sided market problem +#### 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. +#### 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 Stack network. -#### watch-only wallet -A wallet without send and receive ability. You can view only balances and transaction history. +#### Watch-only wallet +A wallet without send 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. From e30b10bdf2a391b293259e90da69afac5fc4acf6 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Tue, 10 Jan 2023 04:26:54 +0100 Subject: [PATCH 0052/1444] New translations nft.md (Portuguese, Brazilian) --- .../current/services-using-stacks/nft.md | 8 ++++++++ 1 file changed, 8 insertions(+) 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 index bfa0505dc9..abb770663c 100644 --- 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 @@ -21,10 +21,18 @@ Please edit this page to add any relevant new site that we are missing. ![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) \ No newline at end of file From 0887768ba4d9c00b950bc5b69792c5f31b566ca5 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Tue, 10 Jan 2023 04:26:55 +0100 Subject: [PATCH 0053/1444] New translations glossary.md (Indonesian) --- .../current/references/glossary.md | 130 ++++++++---------- 1 file changed, 55 insertions(+), 75 deletions(-) diff --git a/i18n/id/docusaurus-plugin-content-docs/current/references/glossary.md b/i18n/id/docusaurus-plugin-content-docs/current/references/glossary.md index 53174e2764..9135bc2bf0 100644 --- a/i18n/id/docusaurus-plugin-content-docs/current/references/glossary.md +++ b/i18n/id/docusaurus-plugin-content-docs/current/references/glossary.md @@ -5,19 +5,16 @@ 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. +A string of letters and numbers. `3E53XjqK4Cxt71BGeP2VhpcotM8LZ853C8` Sharing this address allows anyone to send Bitcoin to the address. -#### block +#### 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 +#### 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) @@ -33,138 +30,127 @@ Looks like a bitcoin address but starts with `ID` for example: `ID-1J3PUxY5uDShU #### 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 +#### 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. +The rules governing the creation of new valid records in a blockchain database and the mining algorithms used for this purpose. -#### control plane +#### 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 +#### Core node A server that runs Stacks Blockchain services. -#### crypto-asset +#### 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 +#### 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) +#### 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 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 +#### 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 +#### 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) +#### 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 +#### Ephemeral key A cryptographic key is called ephemeral if it is generated for each execution of a key establishment process. -#### fork +#### 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 +#### 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. +#### (Digital) Identity +A way to represent a collection of activities in the digital world that are controlled by one or more persons, representatives of an organization or in general an entity, for example a software program. On the Stacks network, an identity is represented by a Stacks address and can have an associated unique name (see BNS) and a public profile. -#### 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". +#### 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. +#### 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. -#### light clients +#### 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 +#### 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 +#### Penambangan 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 +#### 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 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 +#### 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 +#### 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 key -Private keys matches a corresponding public key. A public key also looks like a string of letters and numbers: +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 +#### 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 +#### Proof of work (PoW) 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 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) +#### 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` +#### Secret Key +A different word for "Seed phrase". -#### seed phrase +#### Seed phrase +Used to access one or more identities on the Stacks blockchain and Bitcoin blockchain. The seed phrase consists of 24 words in a sequence. Both the word *and its position in 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`. -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 +#### 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 +#### 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*. " + 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 a 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. @@ -178,32 +164,26 @@ A complete version of our open-source software available on Github at https://gi #### 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 hub +A Gaia instance run by a hub provider or software. A Gaia hub stores data in a separate, addressed location associated with a public key. -#### storage provider +#### Storage provider A third-party company cloud or software provider that hosts one or more Gaia storage hubs. -#### transaction +#### Transaction A transaction is a unit of work within a block. -#### transaction fee -Fees paid by participants in a transaction to miners. +#### Transaction fee +Fees paid by participants of a blockchain to miners for their work to process transactions. -#### two-sided market problem +#### 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. +#### 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 Stack network. -#### watch-only wallet -A wallet without send and receive ability. You can view only balances and transaction history. +#### Watch-only wallet +A wallet without send 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. From 411e048fb855ea48252ad370c92454f1a50bb42a Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Tue, 10 Jan 2023 04:26:58 +0100 Subject: [PATCH 0054/1444] New translations nft.md (Indonesian) --- .../current/services-using-stacks/nft.md | 8 ++++++++ 1 file changed, 8 insertions(+) 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 index bfa0505dc9..abb770663c 100644 --- 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 @@ -21,10 +21,18 @@ Please edit this page to add any relevant new site that we are missing. ![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) \ No newline at end of file From 629733f6b959c6dcfcf88cbd36726812da2a26de Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Tue, 10 Jan 2023 04:26:59 +0100 Subject: [PATCH 0055/1444] New translations glossary.md (Hindi) --- .../current/references/glossary.md | 130 ++++++++---------- 1 file changed, 55 insertions(+), 75 deletions(-) diff --git a/i18n/hi/docusaurus-plugin-content-docs/current/references/glossary.md b/i18n/hi/docusaurus-plugin-content-docs/current/references/glossary.md index 1027a52c96..20474763a7 100644 --- a/i18n/hi/docusaurus-plugin-content-docs/current/references/glossary.md +++ b/i18n/hi/docusaurus-plugin-content-docs/current/references/glossary.md @@ -5,19 +5,16 @@ 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. +A string of letters and numbers. `3E53XjqK4Cxt71BGeP2VhpcotM8LZ853C8` Sharing this address allows anyone to send Bitcoin to the address. -#### block +#### 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 +#### 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) @@ -33,138 +30,127 @@ Looks like a bitcoin address but starts with `ID` for example: `ID-1J3PUxY5uDShU #### 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 +#### 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. +The rules governing the creation of new valid records in a blockchain database and the mining algorithms used for this purpose. -#### control plane +#### 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 +#### Core node A server that runs Stacks Blockchain services. -#### crypto-asset +#### 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 +#### 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) +#### 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 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 +#### 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 +#### 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) +#### 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 +#### Ephemeral key A cryptographic key is called ephemeral if it is generated for each execution of a key establishment process. -#### fork +#### 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 +#### 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. +#### (Digital) Identity +A way to represent a collection of activities in the digital world that are controlled by one or more persons, representatives of an organization or in general an entity, for example a software program. On the Stacks network, an identity is represented by a Stacks address and can have an associated unique name (see BNS) and a public profile. -#### 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". +#### 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. +#### 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. -#### light clients +#### 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 +#### 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 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 +#### 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 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 +#### 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 +#### 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 key -Private keys matches a corresponding public key. A public key also looks like a string of letters and numbers: +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 +#### 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 +#### Proof of work (PoW) 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 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) +#### 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` +#### Secret Key +A different word for "Seed phrase". -#### seed phrase +#### Seed phrase +Used to access one or more identities on the Stacks blockchain and Bitcoin blockchain. The seed phrase consists of 24 words in a sequence. Both the word *and its position in 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`. -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 +#### 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 +#### 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*. " + 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 a 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. @@ -178,32 +164,26 @@ A complete version of our open-source software available on Github at https://gi #### 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 hub +A Gaia instance run by a hub provider or software. A Gaia hub stores data in a separate, addressed location associated with a public key. -#### storage provider +#### Storage provider A third-party company cloud or software provider that hosts one or more Gaia storage hubs. -#### transaction +#### Transaction A transaction is a unit of work within a block. -#### transaction fee -Fees paid by participants in a transaction to miners. +#### Transaction fee +Fees paid by participants of a blockchain to miners for their work to process transactions. -#### two-sided market problem +#### 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. +#### 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 Stack network. -#### watch-only wallet -A wallet without send and receive ability. You can view only balances and transaction history. +#### Watch-only wallet +A wallet without send 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. From 96cc82d74589d7eb408bf28a6da871d075f0ffea Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Tue, 10 Jan 2023 04:27:01 +0100 Subject: [PATCH 0056/1444] New translations nft.md (Hindi) --- .../current/services-using-stacks/nft.md | 8 ++++++++ 1 file changed, 8 insertions(+) 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 index bfa0505dc9..abb770663c 100644 --- 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 @@ -21,10 +21,18 @@ Please edit this page to add any relevant new site that we are missing. ![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) \ No newline at end of file From 04ed15c1a07c44f1476ab907eff46a564321ffe4 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Wed, 18 Jan 2023 00:25:43 +0100 Subject: [PATCH 0057/1444] Update source file glossary.md --- docs/references/glossary.md | 136 +++++++++++++++--------------------- 1 file changed, 56 insertions(+), 80 deletions(-) diff --git a/docs/references/glossary.md b/docs/references/glossary.md index 7253959dc7..921584ddd3 100644 --- a/docs/references/glossary.md +++ b/docs/references/glossary.md @@ -5,21 +5,18 @@ 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. +Sharing this address allows anyone to send Bitcoin to the address. -#### block +#### 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 +#### 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) @@ -36,117 +33,105 @@ Looks like a bitcoin address but starts with `ID` for example: #### 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 +#### 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. +The rules governing the creation of new valid records in a blockchain database and the mining algorithms used for this purpose. -#### control plane +#### 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 +#### Core node A server that runs Stacks Blockchain services. -#### crypto-asset +#### 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 +#### 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) +#### 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 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 +#### 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 +#### 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) +#### 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 +#### Ephemeral key A cryptographic key is called ephemeral if it is generated for each execution of a key establishment process. -#### fork +#### 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 +#### 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. +#### (Digital) Identity +A way to represent a collection of activities in the digital world that are controlled by one or more persons, representatives of an organization or in general an entity, for example a software program. On the Stacks network, an identity is represented by a Stacks address and can have an associated unique name (see BNS) and a public profile. -#### 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". +#### 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. +#### 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. -#### light clients +#### 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 +#### 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 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 +#### 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 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 +#### 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 +#### 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 key -Private keys matches a corresponding public key. A public key also looks like a string of letters and numbers: +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 +#### 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 +#### Proof of work (PoW) 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 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. @@ -154,28 +139,25 @@ The exact format of the public and private key depend on the software you use to #### Public Key Infrastructure (PKI) A system which returns a cryptographic public key associated with a name. -#### replicated state machines (RSMs) +#### 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` +#### Secret Key +A different word for "Seed phrase". -#### 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. +#### Seed phrase +Used to access one or more identities on the Stacks blockchain and Bitcoin blockchain. The seed phrase consists of 24 words in a sequence. Both the word *and its position in 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 + +#### 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 +#### 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*. " + If you created a software-only wallet with a 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. @@ -190,32 +172,26 @@ A complete version of our open-source software available on Github at https://gi 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 hub +A Gaia instance run by a hub provider or software. A Gaia hub stores data in a separate, addressed location associated with a public key. -#### storage provider +#### Storage provider A third-party company cloud or software provider that hosts one or more Gaia storage hubs. -#### transaction +#### Transaction A transaction is a unit of work within a block. -#### transaction fee -Fees paid by participants in a transaction to miners. +#### Transaction fee +Fees paid by participants of a blockchain to miners for their work to process transactions. -#### two-sided market problem +#### 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. +#### 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 Stack network. -#### watch-only wallet -A wallet without send and receive ability. You can view only balances and transaction history. +#### Watch-only wallet +A wallet without send 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. From 556e12cd93eaf732951d63fcec17bcfae03234a0 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Wed, 18 Jan 2023 00:25:44 +0100 Subject: [PATCH 0058/1444] Update source file nft.md --- docs/services-using-stacks/nft.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/docs/services-using-stacks/nft.md b/docs/services-using-stacks/nft.md index bfa0505dc9..abb770663c 100644 --- a/docs/services-using-stacks/nft.md +++ b/docs/services-using-stacks/nft.md @@ -21,10 +21,18 @@ Please edit this page to add any relevant new site that we are missing. ![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) \ No newline at end of file From ccae26c717529a0f438057b2d2c79f44b6446e48 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 29 Jan 2023 07:06:31 +0100 Subject: [PATCH 0059/1444] New translations digitalocean.md (Spanish) --- .../current/nodes-and-miners/digitalocean.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) 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 index 1d3d2b2d28..6307fcd867 100644 --- 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 @@ -18,7 +18,7 @@ Vaya a la página [Stacks Blockchain](https://marketplace.digitalocean.com/apps/ #### 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) +Elija un plan (solo le permitirá seleccionar un plan que cumpla con los requisitos mínimos) y su región de datacenter preferida. ![](/img/sh_digitalocean-choose-plan.png) #### Paso 3 @@ -46,11 +46,11 @@ Necesitarás esperar unos segundos para que el droplet se cree. Una vez creado h ## 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). +Una vez que se ejecuta el droplet, el arranque inicial puede tardar varios minutos mientras se importan los datos de BNS (esta es una operación que se realiza una sola vez). -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`. +Para hacer un seguimiento del progreso, puedes hacer `root@your_droplet_public_ipv4` al host y ejecutar: `/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. +Una vez que la blockchain de Stacks comienza a sincronizar con los pares, los puertos de la aplicación se abrirán y el puerto nginx 80 comenzará ahora a empezar a enviar peticiones. Use `http://your_droplet_public_ipv4` para acceder a los datos directamente, siendo la salida similar a: @@ -66,17 +66,17 @@ Use `http://your_droplet_public_ipv4` para acceder a los datos directamente, sie } ``` -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. +Todos los servicios son administrados por un [systemd unit file](https://github.com/stacksfoundation/stacks-machine-images/blob/master/files/etc/systemd/system/stacks.service) que está configurado para comenzar al arrancar. -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. +El control manual también es posible a través del script [manage.sh](https://github.com/stacks-network/stacks-blockchain-docker/blob/master/manage.sh) en `/opt/stacks-blockchain-docker/manage.sh` en el 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). +Los detalles completos sobre cómo usar el script manage.sh están [disponibles aquí](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). +Además de crear un Droplet desde la aplicación de Stacks Blockchain 1-Click a través del panel de control, también puedes usar la [API de DigitalOcean](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. +Como ejemplo, para crear un Droplet de 4GB Stacks Blockchain en la región SFO2, puede utilizar el siguiente comando curl. 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' \ From 59284c85079bd925946256f1774b9bef6a4d193c Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 29 Jan 2023 09:38:42 +0100 Subject: [PATCH 0060/1444] New translations digitalocean.md (Spanish) --- .../current/nodes-and-miners/digitalocean.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) 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 index 6307fcd867..973ce152fd 100644 --- 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 @@ -76,7 +76,7 @@ Los detalles completos sobre cómo usar el script manage.sh están [disponibles Además de crear un Droplet desde la aplicación de Stacks Blockchain 1-Click a través del panel de control, también puedes usar la [API de DigitalOcean](https://digitalocean.com/docs/api). -Como ejemplo, para crear un Droplet de 4GB Stacks Blockchain en la región SFO2, puede utilizar el siguiente comando curl. 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. +Como ejemplo, para crear un Droplet de 4GB Stacks Blockchain en la región SFO2, puede utilizar el siguiente comando curl. Tendrás que guardar tu [token de acceso a la API](https://docs.digitalocean.com/reference/api/create-personal-access-token/) en una variable de entorno o sustituirlo en el siguiente comando. ```bash curl -X POST -H 'Content-Type: application/json' \ From 4718bad1a6056c7d05a57de9d8561daffc5a7f64 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sat, 4 Feb 2023 19:06:37 +0100 Subject: [PATCH 0061/1444] New translations miner-costs-and-fees.md (Spanish) --- .../current/nodes-and-miners/miner-costs-and-fees.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) 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 index 40397a51e0..7b65679d3b 100644 --- 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 @@ -1,6 +1,6 @@ --- -title: Miner costs and fees -description: Miner Cost and Fee Estimation +title: Costes de Minería y Estimación de comisiones +description: Costes de Minería y Estimación de comisiones sidebar_position: 8 --- From 5337d2f92982034a74661fedebfe38cbcbddfa2f Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:38:04 +0100 Subject: [PATCH 0062/1444] New translations digitalocean.md (Spanish) --- .../current/nodes-and-miners/digitalocean.md | 41 +++++++++++-------- 1 file changed, 25 insertions(+), 16 deletions(-) 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 index 973ce152fd..8b945979d0 100644 --- 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 @@ -1,28 +1,30 @@ --- -title: Stacks en DigitalOcean +title: Run a Node with Digital Ocean description: Una guía para configurar Stacks en DigitalOcean -sidebar_position: 4 +sidebar_position: 2 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). +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) ## 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`. +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`. ![](/img/sh_digitalocean-marketplace.png) #### Paso 2 -Elija un plan (solo le permitirá seleccionar un plan que cumpla con los requisitos mínimos) y su región de datacenter preferida. ![](/img/sh_digitalocean-choose-plan.png) +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) #### Paso 3 -Introduzca una contraseña de root o active las claves SSH si lo prefiere. +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) @@ -46,41 +48,48 @@ Necesitarás esperar unos segundos para que el droplet se cree. Una vez creado h ## Empezando después de desplegar Stacks Blockchain -Una vez que se ejecuta el droplet, el arranque inicial puede tardar varios minutos mientras se importan los datos de BNS (esta es una operación que se realiza una sola vez). +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. Para hacer un seguimiento del progreso, puedes hacer `root@your_droplet_public_ipv4` al host y ejecutar: `/opt/stacks-blockchain-docker/manage.sh -n mainnet -a logs`. -Una vez que la blockchain de Stacks comienza a sincronizar con los pares, los puertos de la aplicación se abrirán y el puerto nginx 80 comenzará ahora a empezar a enviar peticiones. +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` para acceder a los datos directamente, siendo la salida similar a: ```json { - "server_version": "stacks-blockchain-api v3.0.3 (master:cd0c8aef)", + "server_version": "stacks-blockchain-api v6.2.3 (master:77ab3ae2)", "status": "ready", "chain_tip": { - "block_height": 16220, - "block_hash": "0x3123fba9c0de6b569573494cf83c1d5d198a66bfd5f48ef97949b6bf11ba13be", - "index_block_hash": "0xeec960fbbd6186b4ccac85ce12adba72be497d881f81e077305c90955b51a6ae" + "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) ::: + Todos los servicios son administrados por un [systemd unit file](https://github.com/stacksfoundation/stacks-machine-images/blob/master/files/etc/systemd/system/stacks.service) que está configurado para comenzar al arrancar. El control manual también es posible a través del script [manage.sh](https://github.com/stacks-network/stacks-blockchain-docker/blob/master/manage.sh) en `/opt/stacks-blockchain-docker/manage.sh` en el host. -Los detalles completos sobre cómo usar el script manage.sh están [disponibles aquí](https://github.com/stacks-network/stacks-blockchain-docker/blob/master/README.md#quickstart). +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). -## Creación de API +## Launching a Droplet using the DigitalOcean API Además de crear un Droplet desde la aplicación de Stacks Blockchain 1-Click a través del panel de control, también puedes usar la [API de DigitalOcean](https://digitalocean.com/docs/api). Como ejemplo, para crear un Droplet de 4GB Stacks Blockchain en la región SFO2, puede utilizar el siguiente comando curl. Tendrás que guardar tu [token de acceso a la API](https://docs.digitalocean.com/reference/api/create-personal-access-token/) en una variable de entorno o sustituirlo en el siguiente comando. +:::note _The `name`, `region` and `size` values below are hardcoded, so adjust as desired._ ::: + ```bash -curl -X POST -H 'Content-Type: application/json' \ +$ export TOKEN= +$ 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"}' \ + '{"name":"stacks-blockchain","region":"sfo2","size":"s-2vcpu-4gb","image":"stacksfoundation-stacksblockchain"}' \ "https://api.digitalocean.com/v2/droplets" ``` From 5db65c058951179b4f8d422a34c6a00018eef271 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:38:04 +0100 Subject: [PATCH 0063/1444] New translations miner-costs-and-fees.md (Spanish) --- .../current/nodes-and-miners/miner-costs-and-fees.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) 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 index 7b65679d3b..950db7fa52 100644 --- 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 @@ -8,7 +8,7 @@ sidebar_position: 8 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 @@ -22,3 +22,5 @@ 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). From f2c3ea1b2480743ec10fe2f732115a7cb85cd839 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:38:05 +0100 Subject: [PATCH 0064/1444] New translations authentication.md (French) --- .../current/stacks-academy/authentication.md | 63 +++++++++++++++++++ 1 file changed, 63 insertions(+) create mode 100644 i18n/fr/docusaurus-plugin-content-docs/current/stacks-academy/authentication.md diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/stacks-academy/authentication.md b/i18n/fr/docusaurus-plugin-content-docs/current/stacks-academy/authentication.md new file mode 100644 index 0000000000..b135f2f9ce --- /dev/null +++ b/i18n/fr/docusaurus-plugin-content-docs/current/stacks-academy/authentication.md @@ -0,0 +1,63 @@ +--- +title: Authentication +description: Inscription et se connection des utilisateurs avec des identités sur la blockchain de Stacks +sidebar_position: 8 +--- + +## 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. From b04abe18d5aea1ddb5290b872f0f465274380e7d Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:38:06 +0100 Subject: [PATCH 0065/1444] New translations bns.md (French) --- .../current/stacks-academy/bns.md | 242 ++++++++++++++++++ 1 file changed, 242 insertions(+) create mode 100644 i18n/fr/docusaurus-plugin-content-docs/current/stacks-academy/bns.md diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/stacks-academy/bns.md b/i18n/fr/docusaurus-plugin-content-docs/current/stacks-academy/bns.md new file mode 100644 index 0000000000..0a9426e088 --- /dev/null +++ b/i18n/fr/docusaurus-plugin-content-docs/current/stacks-academy/bns.md @@ -0,0 +1,242 @@ +--- +title: Système de nommage de la blockchain +description: Lier les noms d'utilisateur aux états hors chaîne +sidebar_position: 8 +--- + +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. 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). + +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`. + +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 + +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). From 697e2d3475f7d7414b7e782a0d3c8d994df2a6a7 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:38:07 +0100 Subject: [PATCH 0066/1444] New translations docs.md (French) --- .../current/contribute/docs.md | 24 ++++++++++++------- 1 file changed, 15 insertions(+), 9 deletions(-) diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/contribute/docs.md b/i18n/fr/docusaurus-plugin-content-docs/current/contribute/docs.md index 77705451b8..b2fef628f9 100644 --- a/i18n/fr/docusaurus-plugin-content-docs/current/contribute/docs.md +++ b/i18n/fr/docusaurus-plugin-content-docs/current/contribute/docs.md @@ -7,7 +7,7 @@ description: Learn how this site is built, and how you can contribute to it. 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). +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/). @@ -15,7 +15,7 @@ Don't want to learn it? No need to. Write [in plain text an issue on Github](htt :::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 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). @@ -24,28 +24,32 @@ To add new content, they are two different ways to do it, the [easy way](#easy-w [**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. +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 yourhanges in real time. + - `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. -## Aditional information +## 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 ``` @@ -54,8 +58,8 @@ Before running this command for the first time you will need to run `npm install 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 ``` @@ -91,7 +95,7 @@ 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. +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 @@ -124,6 +128,7 @@ And execute prettier with the following command: npx prettier --write mynewfiletocheck.md ``` --> + ### 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. @@ -138,6 +143,7 @@ To write a code block, you need to wrap your code in ` ```language `, and end yo (define-public (get-counter) (ok (var-get counter))) ``` + ### Admonitions You can use the following admonitions to highlight content. @@ -204,4 +210,4 @@ Some **content** with _markdown_ `syntax`. Some **content** with _markdown_ `syntax`. -::: \ No newline at end of file +::: From 0a1b68773ddf15acd99b7510c76fcd40cb188b69 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:38:09 +0100 Subject: [PATCH 0067/1444] New translations translations.md (French) --- .../current/contribute/translations.md | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/contribute/translations.md b/i18n/fr/docusaurus-plugin-content-docs/current/contribute/translations.md index bd9a452333..fe8f8c6027 100644 --- a/i18n/fr/docusaurus-plugin-content-docs/current/contribute/translations.md +++ b/i18n/fr/docusaurus-plugin-content-docs/current/contribute/translations.md @@ -1,25 +1,24 @@ --- title: Contribute with translations -description: Want to help tranlating these docs to your local language? +description: Want to help translating 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. +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 Crodin intead. +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 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 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) From c396bc3a97e06f705ecdf4aa575fa306cf3a3f26 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:38:11 +0100 Subject: [PATCH 0068/1444] New translations gaia-on-ec2.md (French) --- .../current/gaia/gaia-on-ec2.md | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) 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 index 2067e7d57c..3f58ca5e68 100644 --- 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 @@ -26,9 +26,10 @@ Use a link in the table to launch the [CloudFormation](https://console.aws.amazo ### Step 2 - Setup stack using template -You need to configure the template with the appropiate values for your hub and domain it runs on. +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 ``` @@ -52,7 +53,7 @@ Specify the stack details and then click `Next`: ![Specify template](/img/cloudf | 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`. | +| 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 | @@ -93,7 +94,9 @@ ssh -i admin@ 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 +![](/img/cloudformation-gaia-template1-designer.png) From b73fa2b492a0d87f44b7c71f1216ede34848c7df Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:38:12 +0100 Subject: [PATCH 0069/1444] New translations gaia.md (French) --- .../current/gaia/gaia.md | 12 +++++++++--- 1 file changed, 9 insertions(+), 3 deletions(-) diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/gaia/gaia.md b/i18n/fr/docusaurus-plugin-content-docs/current/gaia/gaia.md index 1070857350..f86a0d61dc 100644 --- a/i18n/fr/docusaurus-plugin-content-docs/current/gaia/gaia.md +++ b/i18n/fr/docusaurus-plugin-content-docs/current/gaia/gaia.md @@ -1,14 +1,20 @@ --- title: Gaia description: Decentralized storage architecture for off-chain data -sidebar_position: 5 +sidebar_position: 6 tags: - gaia --- ## Introduction -Apps built with the Stacks blockchain store off-chain data using a storage system called Gaia. +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. @@ -38,7 +44,7 @@ The Stacks blockchain stores only identity data. Data created by the actions of 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) +![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. From 9239707007a719dde466189a7577516378e5e587 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:38:13 +0100 Subject: [PATCH 0070/1444] New translations setup-linux.md (French) --- .../current/gaia/setup-linux.md | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) 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 index db427f890a..2c0ca2b92e 100644 --- a/i18n/fr/docusaurus-plugin-content-docs/current/gaia/setup-linux.md +++ b/i18n/fr/docusaurus-plugin-content-docs/current/gaia/setup-linux.md @@ -1,6 +1,6 @@ --- 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. +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 @@ -19,8 +19,7 @@ This configuration will setup the following 4 docker containers: 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: +**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 @@ -48,8 +47,7 @@ chmod +x ${DESTINATION_DC}/docker-compose 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. +**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 From 18a41fa9778513bac4336c28c5b50e7b2c412d5a Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:38:15 +0100 Subject: [PATCH 0071/1444] New translations digitalocean.md (French) --- .../current/nodes-and-miners/digitalocean.md | 41 +++++++++++-------- 1 file changed, 25 insertions(+), 16 deletions(-) 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 index dd7194f504..15df918d04 100644 --- 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 @@ -1,28 +1,30 @@ --- -title: Stacks on DigitalOcean +title: Run a Node with Digital Ocean description: A guide to setup Stacks on DigitalOcean -sidebar_position: 4 +sidebar_position: 2 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). +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`. +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 plan that meets the minimum requirements) and your prefered datacenter region. ![](/img/sh_digitalocean-choose-plan.png) +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 if your prefer. +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) @@ -46,41 +48,48 @@ Congratulations! You are now running the Stacks Blockchain. You can click on `Co ## 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). +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`. -Once the stacks blockchain starts to sync with peers, application ports will open and nginx port 80 will now start proxying requests. +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 v3.0.3 (master:cd0c8aef)", + "server_version": "stacks-blockchain-api v6.2.3 (master:77ab3ae2)", "status": "ready", "chain_tip": { - "block_height": 16220, - "block_hash": "0x3123fba9c0de6b569573494cf83c1d5d198a66bfd5f48ef97949b6bf11ba13be", - "index_block_hash": "0xeec960fbbd6186b4ccac85ce12adba72be497d881f81e077305c90955b51a6ae" + "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/README.md#quickstart). +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). -## API Creation +## 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 -curl -X POST -H 'Content-Type: application/json' \ +$ export TOKEN= +$ 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"}' \ + '{"name":"stacks-blockchain","region":"sfo2","size":"s-2vcpu-4gb","image":"stacksfoundation-stacksblockchain"}' \ "https://api.digitalocean.com/v2/droplets" ``` From e6fde2c4b0caa6081d9420bbf03c38c9b0cf9efc Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:38:15 +0100 Subject: [PATCH 0072/1444] New translations index.md (French) --- .../current/nodes-and-miners/index.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) 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 index b6cbb9754a..e5f4f2c250 100644 --- 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 @@ -1,11 +1,11 @@ --- title: Nodes and Miners description: Nodes and Miners -sidebar_position: 7 +sidebar_position: 5 --- -Here are all the steps to run nodes and miners, both on mainnet and testnet. +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. -## What's a Stacks node? +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. -## What's a Stacks miner? +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. From eca036bd4cbe64ba5f05322619a8a0de37f8b0f1 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:38:16 +0100 Subject: [PATCH 0073/1444] New translations miner-mainnet.md (French) --- .../current/nodes-and-miners/miner-mainnet.md | 301 +++++++----------- 1 file changed, 110 insertions(+), 191 deletions(-) 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 index 305ad0b5ca..5afd34c23f 100644 --- 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 @@ -1,166 +1,100 @@ --- title: Mine mainnet Stacks tokens -description: Set up and run a miner on the Stacks 2.0 mainnet -sidebar_position: 5 +description: Set up and run a miner on Stacks Mainnet +sidebar_position: 6 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. +For more on the technical details of mining, please review the [mining guide](../stacks-academy/mining) -If you're interested in mining on the testnet, you can find instructions on how to do that [here](miner-testnet): +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 want to learn more about the technical details of mining, please review the [mining guide](../understand-stacks/mining): +If you're interested in mining on the Stacks testnet, you can find instructions on how to do that [here](miner-testnet): -## Running bitcoind locally +## Running a Bitcoin Mainnet Full Node -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) +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. -First, download the bitcoind software for your platform from https://bitcoin.org/en/download. +- [Ensure your computer meets the minimum hardware requirements before continuing.](https://bitcoin.org/en/bitcoin-core/features/requirements#system-requirements) -Next, start bitcoind with the following configuration: +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): -```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 -``` +:::tip It is recommened to use a persistent location for the chainstate, in the steps below we're using `/bitcoin` ::: -Finally, start bitcoind as follows: +### Update the Bitcoin Configuration File -```bash -bitcoind -conf=path/to/bitcoin.conf -``` - -It may take a few days for the node to synchronize with the Bitcoin mainnet. +Next, update the bitcoin configuration: -## 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 : +- **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 -[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 = "" -... +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 ``` -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. +### Start Bitcoin -To run your miner, run this in the command line: +Finally, start bitcoin as follows (adjust the `conf` path to where it was created in the previous step, i.e. `$HOME/bitcoin.conf`): ```bash -stacks-node start --config=./testnet/stacks-node/conf/mainnet-miner-conf.toml +bitcoind -conf=$HOME/bitcoin.conf ``` -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 -``` +:::note +It will take a few days for the node to synchronize with Bitcoin mainnet. +::: -The above code will compile an optimized binary. To use it, run: +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 -cd ../.. -./target/release/stacks-node start --config=./mainnet-miner-conf.toml +$ bitcoin-cli \ + -rpcconnect=localhost \ + -rpcport=8332 \ + -rpcuser=btcuser \ + -rpcpassword=btcpassword \ +getblockchaininfo | jq .blocks +773281 ``` -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 Stacks Blockchain miner -## Running a miner in Windows +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) -### Prerequisites +_There may be some extra requirements to building, [defined here](https://github.com/stacksfoundation/miner-docs/blob/main/prerequisites.md#install-required-packages)_ -Make sure are [running a node](run-a-node) and [running bitcoind locally](#running-bitcoind-locally) before starting this tutorial. +:::tip It is recommened to use a persistent location for the chainstate, in the steps below we're using `/stacks-blockchain` ::: -### Generate keychain and get mainnet tokens in Windows +### Generate a keychain -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 cryptocurrency 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: +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 -npm install --global @stacks/cli -stx make_keychain > cli_keychain.json -type cli_keychain.json +npx @stacks/cli make_keychain 2>/dev/null | jq -r ``` -After this runs, you'll probably see some installation logs, and at the end you should see some JSON that looks like this: +After this runs, you should see some JSON printed to the screen that looks like this: ```json { @@ -174,109 +108,99 @@ After this runs, you'll probably see some installation logs, and at the end you } ``` -:::tip Check out the [Stacks CLI reference](https://docs.hiro.so/references/stacks-cli) for more details ::: +:::warning **Do not lose this information** - we'll need to use the `privateKey` and `btcAddress` fields in later steps. ::: -The above BTC address will then need to be imported into the BTC network. +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=your-user -rpcpassword=your-password importaddress +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 configuration file + + +### Update the Stacks Blockchain 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). +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`. -Mettez à jour les propriétés suivantes : +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] -... -# Enter your private key here -seed = "replace-with-your-private-key" -local_peer_seed = "replace-with-your-private-key" -... +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] -... -# To mine on mainnet, you need to run bitcoind locally -# Details can be found in above section, 'Running bitcoind locally' +chain = "bitcoin" +mode = "mainnet" peer_host = "127.0.0.1" -username = "" -password = "" -... +username = "" +password = "" +rpc_port = 8332 +peer_port = 8333 +satoshis_per_byte = 100 +burn_fee_cap = 20000 ``` -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 +### Start the Stacks Blockchain -To start your miner, run this in the command line: +To run your miner, run this in the command line: ```bash -stacks-node start --config=testnet/stacks-node/conf/mainnet-miner-conf.toml +stacks-node start --config=$HOME/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 +### 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 -set RUST_BACKTRACE=full; -set STACKS_LOG_DEBUG=1; -stacks-node start --config=mainnet-miner-conf.toml +STACKS_LOG_DEBUG=1 stacks-node start --config=$HOME/mainnet-miner-conf.toml ``` -## Optional: Running with Docker +--- + +## Optional: Running a Stacks Blockchain miner with Docker -Alternatively, you can run the mainnet node with Docker. +Alternatively, you can run a Stacks mainnet miner with Docker. -:::caution Ensure you have [Docker](https://docs.docker.com/get-docker/) installed on your machine. ::: +:::caution Ensure you have [Docker](https://docs.docker.com/get-docker/) installed. ::: -### Generate keychain and get tokens +### 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 +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 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 : +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). -```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 = "" -... -``` +### Update Stacks Blockchain Docker Configuration File -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. +Use the steps oulined above to create the [configuration file](miner-mainnet#update-the-stacks-blockchain-configuration-file) -### Start the miner +### 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 ::: @@ -287,7 +211,8 @@ docker run -d \ --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" \ + -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 \ @@ -302,9 +227,9 @@ 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). +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 on your machine: +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) @@ -313,13 +238,7 @@ Ensure you have the following prerequisites installed on your machine: ### 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). +Use the steps [outlined above](miner-mainnet#generate-a-keychain-and-get-some-tokens) ### Install the chart and run the miner From 9f205667914451eeb9d7f9df75b6d7b0f8e3213a Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:38:17 +0100 Subject: [PATCH 0074/1444] New translations miner-testnet.md (French) --- .../current/nodes-and-miners/miner-testnet.md | 318 +++++++----------- 1 file changed, 130 insertions(+), 188 deletions(-) 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 index fbc4c25f00..c0a27e63d5 100644 --- 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 @@ -1,35 +1,52 @@ --- title: Mine testnet Stacks tokens -description: Set up and run a miner on the Stacks 2.0 testnet -sidebar_position: 4 +description: Set up and run a miner on Stacks Testnet +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 testnet. +For more on the technical details of mining, please review the [mining guide](../stacks-academy/mining) -If you want to learn more about the technical details of mining, please review the [mining guide](../understand-stacks/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)). -## Running bitcoind locally +If you're interested in mining on the Stacks mainnet, you can find instructions on how to do that [here](miner-mainnet): -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) +## Running a Bitcoin Testnet Full Node -First, download the bitcoind software for your platform from https://bitcoin.org/en/download. +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. -Next, start bitcoind with the following configuration: +- [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 -rpcuser=your-bitcoind-username -rpcpassword=your-bitcoind-password testnet=1 -txindex=0 -listen=1 -rpcserialversion=0 -maxorphantx=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 @@ -37,126 +54,51 @@ 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" -... +### Start Bitcoin -[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: +Finally, start bitcoind as follows: ```bash -stacks-node start --config=./testnet/stacks-node/conf/testnet-miner-conf.toml +bitcoind -conf=$HOME/bitcoin.conf ``` -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 -``` +:::note +It will take a few hours for the node to synchronize with Bitcoin testnet. +::: -The above code will compile an optimized binary. To use it, run: +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 -cd ../.. -./target/release/stacks-node start --config=./testnet/conf/testnet-follower-conf.toml +$ bitcoin-cli \ + -rpcconnect=localhost \ + -rpcport=18332 \ + -rpcuser=btcuser \ + -rpcpassword=btcpass \ +getblockchaininfo | jq .blocks +2417570 ``` -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 +## Running a Stacks Blockchain miner -### Prerequisites +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) -Make sure are [running a testnet node](run-a-node) before starting this tutorial. +_There may be some extra requirements to building, [defined here](https://github.com/stacksfoundation/miner-docs/blob/main/prerequisites.md#install-required-packages)_ -### Generate keychain and get testnet tokens in Windows +:::tip It is recommened to use a persistent location for the chainstate, in the steps below we're using `/stacks-blockchain` ::: -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. +### Generate a keychain -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. +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. -Generate a keychain: +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 -npm install --global @stacks/cli -stx make_keychain -t > cli_keychain.json -type cli_keychain.json +npx @stacks/cli make_keychain -t 2>/dev/null | jq -r ``` -After this runs, you'll probably see some installation logs, and at the end you should see some JSON that looks like this: +After this runs, you should see some JSON printed to the screen that looks like this: ```json { @@ -170,107 +112,110 @@ After this runs, you'll probably see some installation logs, and at the end you } ``` -:::tip Check out the [Stacks CLI reference](https://docs.hiro.so/references/stacks-cli) for more details ::: +:::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. -Request BTC from faucet: +### Update the Stacks Blockchain Configuration File -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/). +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`. -### Update configuration file +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. -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). +Next, update the bitcoin configuration: -Mettez à jour les propriétés suivantes : +- **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] -... -seed = "replace-with-your-private-key" -local_peer_seed = "replace-with-your-private-key" -... +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] -... -# To mine on Testnet, you need to run bitcoind locally -# Details can be found in above section, 'Running bitcoind locally' +chain = "bitcoin" +mode = "xenon" peer_host = "127.0.0.1" -username = "" -password = "" -... +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 ``` -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 +### Start the Stacks Blockchain -To start your miner, run this in the command line: +To run your miner, run this in the command line: ```bash -stacks-node start --config=testnet/stacks-node/conf/testnet-miner-conf.toml +stacks-node start --config=$HOME/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 +### 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 -set RUST_BACKTRACE=full; -set STACKS_LOG_DEBUG=1; -stacks-node start --config=testnet-miner-conf.toml +STACKS_LOG_DEBUG=1 stacks-node start --config=$HOME/testnet-miner-conf.toml ``` -## Optional: Running with Docker +--- + +## Optional: Running a Stacks Blockchain miner with Docker -Alternatively, you can run the testnet node with Docker. +Alternatively, you can run a Stacks testnet miner with Docker. -:::warning Ensure you have [Docker](https://docs.docker.com/get-docker/) installed on your machine. ::: +:::caution Ensure you have [Docker](https://docs.docker.com/get-docker/) installed ::: -### Generate keychain and get testnet tokens +### Generate a Keychain and Get Some Tokens Generate a keychain: ```bash -docker run -i node:14-alpine npx @stacks/cli make_keychain -t 2>/dev/null +docker run -i node:14-alpine npx @stacks/cli make_keychain 2>/dev/null | jq -r ``` -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 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. -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 Stacks Blockchain Docker Configuration File -Mettez à jour les propriétés suivantes : +Use the steps oulined above to create the [configuration file](miner-testnet#update-the-stacks-blockchain-configuration-file) -```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 +### 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 ::: @@ -281,7 +226,8 @@ docker run -d \ --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" \ + -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 \ @@ -294,26 +240,22 @@ You can review the node logs with this command: 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). +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 on your machine: +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 testnet tokens - -Generate a keychain: - -```bash -docker run -i node:14-alpine npx @stacks/cli make_keychain -t 2>/dev/null -``` +### Generate keychain and get some tokens -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/). +Use the steps [outlined above](miner-testnet#generate-a-keychain-and-get-some-tokens) ### Install the chart and run the miner @@ -324,7 +266,7 @@ 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.node.seed="replace-with-your-privateKey-from-generate-keychain-step" \ ``` You can review the node logs with this command: From 96cf2f6ea0d5998064dd77253ca25cf66b98f8f1 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:38:18 +0100 Subject: [PATCH 0075/1444] New translations stacks-node-configuration.md (French) --- .../stacks-node-configuration.md | 158 +++++++++++------- 1 file changed, 101 insertions(+), 57 deletions(-) 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 index 89af343dc6..cd216e7103 100644 --- 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 @@ -1,7 +1,7 @@ --- title: Stacks Node Configuration description: Configuration parameters and options for the stacks-node binary -sidebar_position: 6 +sidebar_position: 4 --- ## Usage @@ -10,97 +10,141 @@ sidebar_position: 6 stacks-node sub-command [--subcommand-option ] ``` -## Subcommands +### 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 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 -### mocknet +## Configuration File Options -Start a node based on a fast local setup emulating a burnchain. Ideal for smart contract development. +The Stacks Blockchain configuration file has multiple sections under which an option may be placed. -Example: +- [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) -```bash -stacks-node mocknet -``` +For reference, several configuration file examples are [available here](https://github.com/stacks-network/stacks-blockchain/tree/master/testnet/stacks-node/conf) -### krypton +- [Example mainnet follower configuration](./stacks-node-configuration#example-mainnet-follower-configuration) -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). +### node -Example: +Contains various configuration options for the stacks-node binary. -```bash -stacks-node krypton -``` +| 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. | -### testnet +### events_observer -Start a node that will join and stream blocks from the public testnet. +:::info This section is _optional_ and not required -Example: +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. -```bash -stacks-node testnet -``` +| 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. | | -### mainnet +### connection_options -Start a node that joins and streams blocks from the public mainnet. +:::info This section is _optional_ and not required. -Example: +However, if this section is added, **all** fields are required ::: -```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. +Specifies configuration options for others connecting to the stacks node. -#### Arguments +| 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 | -**--config**: relative or absolute path to the TOML config file. Required. +### burnchain -Example: +This section contains configuration options pertaining to the blockchain the stacks-node binds to on the backend for proof-of-transfer (BTC). -```bash -stacks-node start --config=/path/to/config.toml -``` +| 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` | -See [Configuration File Options](#configuration-file-options) for more information. +#### Mining -#### version +| 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`. | -Displays information about the current version and the release cycle. +### ustx_balance -Example: +- `mocknet`/`testnet` only -```bash -stacks-node version -``` +This section contains configuration options allocating microSTX per address in the genesis block -#### help +This section can repeat multiple times, but each section can only define a single address. -Displays a help message. +:::info This section is only required for the `testnet` and `mocknet` networks. -Example: +However, if this section is added, **all** fields are required ::: -```bash -stacks-node help -``` +| 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 | -## Configuration File Options +## Example Mainnet Follower Configuration -The TOML configuration file has multiple sections under which an option may be placed. +```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" -To see a list of example configurations, [please see this page](https://github.com/stacks-network/stacks-blockchain/tree/master/testnet/stacks-node/conf). +[burnchain] +chain = "bitcoin" +mode = "mainnet" +peer_host = "localhost" +username = "user" +password = "pass" +rpc_port = 8332 +peer_port = 8333 -### Section: node +[[events_observer]] +endpoint = "localhost:3700" +retry_count = 255 +events_keys = ["*"] +``` -Contains various configuration options pertaining to the stacks-node. -Example: + From fa09f365893bd5e32af83f00b66afe895b06eb67 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:38:19 +0100 Subject: [PATCH 0076/1444] New translations accounts.md (French) --- .../current/stacks-academy/accounts.md | 215 ++++++++++++++++++ 1 file changed, 215 insertions(+) create mode 100644 i18n/fr/docusaurus-plugin-content-docs/current/stacks-academy/accounts.md diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/stacks-academy/accounts.md b/i18n/fr/docusaurus-plugin-content-docs/current/stacks-academy/accounts.md new file mode 100644 index 0000000000..55d0165def --- /dev/null +++ b/i18n/fr/docusaurus-plugin-content-docs/current/stacks-academy/accounts.md @@ -0,0 +1,215 @@ +--- +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" + } + } + ] +} +``` From 7c84b0674ce050b0a94a385b15de517f4a8dd858 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:38:20 +0100 Subject: [PATCH 0077/1444] New translations microblocks.md (French) --- .../current/stacks-academy/microblocks.md | 107 ++++++++++++++++++ 1 file changed, 107 insertions(+) create mode 100644 i18n/fr/docusaurus-plugin-content-docs/current/stacks-academy/microblocks.md diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/stacks-academy/microblocks.md b/i18n/fr/docusaurus-plugin-content-docs/current/stacks-academy/microblocks.md new file mode 100644 index 0000000000..9310aa65be --- /dev/null +++ b/i18n/fr/docusaurus-plugin-content-docs/current/stacks-academy/microblocks.md @@ -0,0 +1,107 @@ +--- +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. + +[provides an endpoint]: https://docs.hiro.so/get-started/stacks-blockchain-api#nonce-handling +[microblocks_api]: https://docs.hiro.so/api#tag/Microblocks From 132a4ec05a6c1b94481f7152a6f42bc2ed18a1b3 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:38:21 +0100 Subject: [PATCH 0078/1444] New translations mining.md (French) --- .../current/stacks-academy/mining.md | 84 +++++++++++++++++++ 1 file changed, 84 insertions(+) create mode 100644 i18n/fr/docusaurus-plugin-content-docs/current/stacks-academy/mining.md diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/stacks-academy/mining.md b/i18n/fr/docusaurus-plugin-content-docs/current/stacks-academy/mining.md new file mode 100644 index 0000000000..e6e93e130a --- /dev/null +++ b/i18n/fr/docusaurus-plugin-content-docs/current/stacks-academy/mining.md @@ -0,0 +1,84 @@ +--- +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 From 6c0a49cfe53d7f7596cce32e30c6efa45432a88a Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:38:22 +0100 Subject: [PATCH 0079/1444] New translations network.md (French) --- .../current/stacks-academy/network.md | 148 ++++++++++++++++++ 1 file changed, 148 insertions(+) create mode 100644 i18n/fr/docusaurus-plugin-content-docs/current/stacks-academy/network.md diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/stacks-academy/network.md b/i18n/fr/docusaurus-plugin-content-docs/current/stacks-academy/network.md new file mode 100644 index 0000000000..a0dc623d97 --- /dev/null +++ b/i18n/fr/docusaurus-plugin-content-docs/current/stacks-academy/network.md @@ -0,0 +1,148 @@ +--- +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 +} +``` From 2c52d1e5b8426cb328029d2db0ce2a6d8bdfea26 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:38:23 +0100 Subject: [PATCH 0080/1444] New translations stacking.md (French) --- .../current/stacks-academy/stacking.md | 151 ++++++++++++++++++ 1 file changed, 151 insertions(+) create mode 100644 i18n/fr/docusaurus-plugin-content-docs/current/stacks-academy/stacking.md diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/stacks-academy/stacking.md b/i18n/fr/docusaurus-plugin-content-docs/current/stacks-academy/stacking.md new file mode 100644 index 0000000000..545f538ecb --- /dev/null +++ b/i18n/fr/docusaurus-plugin-content-docs/current/stacks-academy/stacking.md @@ -0,0 +1,151 @@ +--- +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. 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. + +![](/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 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 (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 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) From 84659291b656947fa403d4da0631e2fdecbe9d7c Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:38:24 +0100 Subject: [PATCH 0081/1444] New translations technical-specs.md (French) --- .../current/stacks-academy/technical-specs.md | 79 +++++++++++++++++++ 1 file changed, 79 insertions(+) create mode 100644 i18n/fr/docusaurus-plugin-content-docs/current/stacks-academy/technical-specs.md diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/stacks-academy/technical-specs.md b/i18n/fr/docusaurus-plugin-content-docs/current/stacks-academy/technical-specs.md new file mode 100644 index 0000000000..695f849e1a --- /dev/null +++ b/i18n/fr/docusaurus-plugin-content-docs/current/stacks-academy/technical-specs.md @@ -0,0 +1,79 @@ +--- +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). +- 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 whitepaper v2](https://www.youtube.com/watch?v=Wd-Bfe8Sn-Y). From fdbdebd7e30ef816a7db1aa469e192fa88bd7251 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:38:24 +0100 Subject: [PATCH 0082/1444] New translations testnet.md (French) --- .../current/stacks-academy/testnet.md | 35 +++++++++++++++++++ 1 file changed, 35 insertions(+) create mode 100644 i18n/fr/docusaurus-plugin-content-docs/current/stacks-academy/testnet.md diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/stacks-academy/testnet.md b/i18n/fr/docusaurus-plugin-content-docs/current/stacks-academy/testnet.md new file mode 100644 index 0000000000..f8b9f03df2 --- /dev/null +++ b/i18n/fr/docusaurus-plugin-content-docs/current/stacks-academy/testnet.md @@ -0,0 +1,35 @@ +--- +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. + +### 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) From 61807fd019413756449da979327dcb99dda16c64 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:38:25 +0100 Subject: [PATCH 0083/1444] New translations transactions.md (French) --- .../current/stacks-academy/transactions.md | 40 +++++++++++++++++++ 1 file changed, 40 insertions(+) create mode 100644 i18n/fr/docusaurus-plugin-content-docs/current/stacks-academy/transactions.md diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/stacks-academy/transactions.md b/i18n/fr/docusaurus-plugin-content-docs/current/stacks-academy/transactions.md new file mode 100644 index 0000000000..ba6b18f0f7 --- /dev/null +++ b/i18n/fr/docusaurus-plugin-content-docs/current/stacks-academy/transactions.md @@ -0,0 +1,40 @@ +--- +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). ::: From 8cc5214732772aa46dae33b578a83415df8590d1 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:38:27 +0100 Subject: [PATCH 0084/1444] New translations language-functions.md (French) --- .../current/clarity/language-functions.md | 2031 +++++++++++++++++ 1 file changed, 2031 insertions(+) create mode 100644 i18n/fr/docusaurus-plugin-content-docs/current/clarity/language-functions.md diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/clarity/language-functions.md b/i18n/fr/docusaurus-plugin-content-docs/current/clarity/language-functions.md new file mode 100644 index 0000000000..0325c1ac40 --- /dev/null +++ b/i18n/fr/docusaurus-plugin-content-docs/current/clarity/language-functions.md @@ -0,0 +1,2031 @@ +--- +title: Functions +description: See a detailed list of all functions for the Clarity language. +sidebar_position: 3 +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: + +#### 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-existent\"))))) ;; 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-existent\") ;; 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-existent\" })) ;; 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-existent\" }))) ;; 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-existent\" }))) ;; 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 \"Stacks\" '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 successfully 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_ transferred from another principal, but rather minted. + +If a non-positive amount is provided to mint, this function returns `(err 1)`. Otherwise, on successfully 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_ transferred 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 successfully 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 successfully 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)) +``` From 28933935747bf41a03f9bf6dacc47717f322faf5 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:38:28 +0100 Subject: [PATCH 0085/1444] New translations language-keywords.md (French) --- .../current/clarity/language-keywords.md | 146 ++++++++++++++++++ 1 file changed, 146 insertions(+) create mode 100644 i18n/fr/docusaurus-plugin-content-docs/current/clarity/language-keywords.md diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/clarity/language-keywords.md b/i18n/fr/docusaurus-plugin-content-docs/current/clarity/language-keywords.md new file mode 100644 index 0000000000..1aca5359c3 --- /dev/null +++ b/i18n/fr/docusaurus-plugin-content-docs/current/clarity/language-keywords.md @@ -0,0 +1,146 @@ +--- +title: Keywords +description: See a detailed list of all keywords for the Clarity language. +sidebar_position: 4 +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 +``` From bc4615944f3b11fd7c0f596651bc2b1f86d9a0ac Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:38:28 +0100 Subject: [PATCH 0086/1444] New translations language-types.md (French) --- .../current/clarity/language-types.md | 25 +++++++++++++++++++ 1 file changed, 25 insertions(+) create mode 100644 i18n/fr/docusaurus-plugin-content-docs/current/clarity/language-types.md diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/clarity/language-types.md b/i18n/fr/docusaurus-plugin-content-docs/current/clarity/language-types.md new file mode 100644 index 0000000000..0af4577dc9 --- /dev/null +++ b/i18n/fr/docusaurus-plugin-content-docs/current/clarity/language-types.md @@ -0,0 +1,25 @@ +--- +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. | From 6decd16711f8d76dc836dea40d3601aa4b622d43 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:38:30 +0100 Subject: [PATCH 0087/1444] New translations miner-costs-and-fees.md (French) --- .../current/nodes-and-miners/miner-costs-and-fees.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) 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 index 40397a51e0..dd8ee721cc 100644 --- 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 @@ -8,7 +8,7 @@ sidebar_position: 8 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 @@ -22,3 +22,5 @@ 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). From 842724e8902e857b34f16684c33e5817a1815c0e Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:38:31 +0100 Subject: [PATCH 0088/1444] New translations verify-miner.md (French) --- .../current/nodes-and-miners/verify-miner.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) 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 index 094e3f03a1..18e8dd3a48 100644 --- 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 @@ -7,7 +7,7 @@ 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 +$ 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 -``` \ No newline at end of file +``` From 40a2c0fc31318001528be8491de0282f00952c28 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:38:32 +0100 Subject: [PATCH 0089/1444] New translations stacks-blockchain-api.md (French) --- .../stacks-academy/stacks-blockchain-api.md | 41 +++++++++++++++++++ 1 file changed, 41 insertions(+) create mode 100644 i18n/fr/docusaurus-plugin-content-docs/current/stacks-academy/stacks-blockchain-api.md diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/stacks-academy/stacks-blockchain-api.md b/i18n/fr/docusaurus-plugin-content-docs/current/stacks-academy/stacks-blockchain-api.md new file mode 100644 index 0000000000..938bdcd481 --- /dev/null +++ b/i18n/fr/docusaurus-plugin-content-docs/current/stacks-academy/stacks-blockchain-api.md @@ -0,0 +1,41 @@ +--- +title: API de la blockchain Stacks +description: Interagir avec la Blockchain Stacks 2.0 via l'API +sidebar_position: 6 +--- + +## Introduction +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. + +:::tip API Documentation La documentation officielle de l'API est disponible [ici](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 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). ::: + +The RPC API can be used without any authorization. Le chemin de base de l'API est : + +```bash +# pour mainnet, remplacez `testnet` par `mainnet` +https://stacks-node-api.testnet.stacks.co/ +``` + +## Points d'entrée du proxy Hiro pour de l'API RPC Stacks +The Stacks 2.0 Blockchain API (Hiro's API) is centrally hosted. 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. + +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`. ::: From 3819fe0b97f01f011c7762edc4dfdb8c47e46c51 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:38:33 +0100 Subject: [PATCH 0090/1444] New translations run-a-node.md (French) --- .../current/nodes-and-miners/run-a-node.md | 329 +++--------------- 1 file changed, 42 insertions(+), 287 deletions(-) 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 index 94d938c5ca..2993568ce4 100644 --- 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 @@ -1,5 +1,5 @@ --- -title: Run a node +title: Run a Node with Docker description: Set up and run a Stacks node sidebar_position: 1 tags: @@ -8,344 +8,99 @@ tags: ## Stacks Blockchain with Docker -Run your own Stacks Blockchain node easily with just few commands. +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) -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](./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) -## **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 -``` +## **Requirements:** -- With optional proxy: +The **minimum viable requirements** are listed below. -```bash -./manage.sh -n -a start -f proxy -``` +While you _can_ run a node using these specs, it's _recommended_ to assign more than the minimum for better performance. -- With optional bitcoin node: +- ⚠️ [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_ ) -```bash -./manage.sh -n -a start -f bitcoin -``` +:::caution MacOS with an ARM processor is NOT recommended -5. **Stop the Services** +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. ::: -```bash -./manage.sh -n -a stop -``` - -6. **Retrieve Service Logs** - -```bash -./manage.sh -n -a logs -``` - -- Export docker log files to `./exported-logs`: +## **Quickstart** -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. +The `` placeholder used below can be replaced with one of: -```bash -./manage.sh -n -a logs export -``` +- mainnet +- testnet +- mocknet -7. **Restart all services** +1. **Clone the stacks-blockchain-docker repository locally** ```bash -./manage.sh -n -a restart +git clone https://github.com/stacks-network/stacks-blockchain-docker && cd stacks-blockchain-docker ``` -- With optional proxy: +2. **Start the Services** ```bash -./manage.sh -n -a restart -f proxy +./manage.sh -n -a start ``` -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. +:::note With an optional HTTP proxy on port 80: ```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. - +./manage.sh -n -a start -f proxy ``` -9. **Download BNS data to** `./persistent-data/bns-data` - -```bash -./manage.sh bns -``` +::: -10. **Export stacks-blockchain-api events** (_Not applicable for mocknet_) +## **Accessing the services** -```bash -./manage.sh -n -a export -# check logs for completion -./manage.sh -n -a restart -``` +:::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. -11. **Replay stacks-blockchain-api events** (_Not applicable for mocknet_) +Follow the logs to track the sync progress: ```bash -./manage.sh -n -a import -# check logs for completion -./manage.sh -n -a restart +./manage.sh -n -a logs ``` -## **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` +- Ports `20443-20444` are exposed on `localhost` ```bash -curl -sL localhost:20443/v2/info | jq +curl -sL localhost:20443/v2/info | jq -r ``` **stacks-blockchain-api**: -- Port `3999` are exposed to `localhost` +- Port `3999` is exposed on `localhost` ```bash -curl -sL localhost:3999/v2/info | jq +curl -sL localhost:3999 | jq -r ``` **proxy**: -- Port `80` is exposed to `localhost` +- Port `80` is exposed on `localhost` ```bash -curl -sL localhost/v2/info | jq -curl -sL localhost/ | jq +curl -sL localhost/v2/info | jq -r +curl -sL localhost | jq -r ``` --- ## 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 -``` +:::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): ::: --- - -## **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 From a7ba9aabeb53d033a420ffab8adde45b1a01e89d Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:38:34 +0100 Subject: [PATCH 0091/1444] New translations index.md (French) --- .../current/clarity/index.md | 58 +++++++++++++++++++ 1 file changed, 58 insertions(+) create mode 100644 i18n/fr/docusaurus-plugin-content-docs/current/clarity/index.md diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/clarity/index.md b/i18n/fr/docusaurus-plugin-content-docs/current/clarity/index.md new file mode 100644 index 0000000000..903de93a45 --- /dev/null +++ b/i18n/fr/docusaurus-plugin-content-docs/current/clarity/index.md @@ -0,0 +1,58 @@ +--- +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?2 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. If you are unsure what this means, let it not worry you for now. The serious advantage of decidability will become more apparent over time. + +### 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. From 48b44efb878c495934010b1266d8729b753b9a72 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:38:34 +0100 Subject: [PATCH 0092/1444] New translations index.md (French) --- .../current/stacks-academy/index.md | 11 +++++++++++ 1 file changed, 11 insertions(+) create mode 100644 i18n/fr/docusaurus-plugin-content-docs/current/stacks-academy/index.md diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/stacks-academy/index.md b/i18n/fr/docusaurus-plugin-content-docs/current/stacks-academy/index.md new file mode 100644 index 0000000000..a5bdb3c790 --- /dev/null +++ b/i18n/fr/docusaurus-plugin-content-docs/current/stacks-academy/index.md @@ -0,0 +1,11 @@ +--- +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. From e9f12738f56f058b42a7cfee018800f61e538881 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:38:35 +0100 Subject: [PATCH 0093/1444] New translations proof-of-transfer.md (French) --- .../stacks-academy/proof-of-transfer.md | 83 +++++++++++++++++++ 1 file changed, 83 insertions(+) create mode 100644 i18n/fr/docusaurus-plugin-content-docs/current/stacks-academy/proof-of-transfer.md diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/stacks-academy/proof-of-transfer.md b/i18n/fr/docusaurus-plugin-content-docs/current/stacks-academy/proof-of-transfer.md new file mode 100644 index 0000000000..50f4b739d6 --- /dev/null +++ b/i18n/fr/docusaurus-plugin-content-docs/current/stacks-academy/proof-of-transfer.md @@ -0,0 +1,83 @@ +--- +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. From 0df3bc4f1e90dea5c315f221100d83e374033fb2 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:38:36 +0100 Subject: [PATCH 0094/1444] New translations what-is-stacks.md (French) --- .../current/stacks-academy/what-is-stacks.md | 102 ++++++++++++++++++ 1 file changed, 102 insertions(+) create mode 100644 i18n/fr/docusaurus-plugin-content-docs/current/stacks-academy/what-is-stacks.md diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/stacks-academy/what-is-stacks.md b/i18n/fr/docusaurus-plugin-content-docs/current/stacks-academy/what-is-stacks.md new file mode 100644 index 0000000000..94277da8a9 --- /dev/null +++ b/i18n/fr/docusaurus-plugin-content-docs/current/stacks-academy/what-is-stacks.md @@ -0,0 +1,102 @@ +--- +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. + +There's a lot of jargon, possible assumptions, controversy, and cool technology wrapped up in those statements. So let's get started by getting a 30,000 foot view of what exactly Stacks is. + +## Stacks Explained in (Slightly Less Than) 10 Minutes + +
+ +
+ +## 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, Stacks takes a different approach. + +## 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). + +By taking this 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 with some unique properties, like having its own token, that allow it to maintain a historical ledger of all of its transactions and operate with its own security budget. + +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_. + +Nope. 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. From 325fe596125dc486425830caed7a316eaca136b1 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:38:37 +0100 Subject: [PATCH 0095/1444] New translations community-tutorials.md (French) --- .../current/tutorials/community-tutorials.md | 24 +++++++++++++++++++ 1 file changed, 24 insertions(+) create mode 100644 i18n/fr/docusaurus-plugin-content-docs/current/tutorials/community-tutorials.md diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/tutorials/community-tutorials.md b/i18n/fr/docusaurus-plugin-content-docs/current/tutorials/community-tutorials.md new file mode 100644 index 0000000000..a4f3d970ca --- /dev/null +++ b/i18n/fr/docusaurus-plugin-content-docs/current/tutorials/community-tutorials.md @@ -0,0 +1,24 @@ +--- +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/) From 500b7f1e66dd4d152ab9652ec482397630ccd402 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:38:38 +0100 Subject: [PATCH 0096/1444] New translations hello-stacks.md (French) --- .../current/tutorials/hello-stacks.md | 759 ++++++++++++++++++ 1 file changed, 759 insertions(+) create mode 100644 i18n/fr/docusaurus-plugin-content-docs/current/tutorials/hello-stacks.md diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/tutorials/hello-stacks.md b/i18n/fr/docusaurus-plugin-content-docs/current/tutorials/hello-stacks.md new file mode 100644 index 0000000000..a0a442d135 --- /dev/null +++ b/i18n/fr/docusaurus-plugin-content-docs/current/tutorials/hello-stacks.md @@ -0,0 +1,759 @@ +--- +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. From 3dc72742b4bb7ee2faf39ac34923bc287536cdb5 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:38:38 +0100 Subject: [PATCH 0097/1444] New translations index.md (French) --- .../current/tutorials/index.md | 11 +++++++++++ 1 file changed, 11 insertions(+) create mode 100644 i18n/fr/docusaurus-plugin-content-docs/current/tutorials/index.md diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/tutorials/index.md b/i18n/fr/docusaurus-plugin-content-docs/current/tutorials/index.md new file mode 100644 index 0000000000..1d544c7bc1 --- /dev/null +++ b/i18n/fr/docusaurus-plugin-content-docs/current/tutorials/index.md @@ -0,0 +1,11 @@ +--- +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. From c020eb3cb5e217e69dcc61d0293a39c396251efd Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:38:39 +0100 Subject: [PATCH 0098/1444] New translations satoshis-ridge.md (French) --- .../current/tutorials/satoshis-ridge.md | 75 +++++++++++++++++++ 1 file changed, 75 insertions(+) create mode 100644 i18n/fr/docusaurus-plugin-content-docs/current/tutorials/satoshis-ridge.md diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/tutorials/satoshis-ridge.md b/i18n/fr/docusaurus-plugin-content-docs/current/tutorials/satoshis-ridge.md new file mode 100644 index 0000000000..596339ae74 --- /dev/null +++ b/i18n/fr/docusaurus-plugin-content-docs/current/tutorials/satoshis-ridge.md @@ -0,0 +1,75 @@ +--- +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 arguable one of its strengths. + +Instead, we need to create separate layers that add additional functionality without modify 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. From 6f47fa221bac08a616eac6a8b73ee52dd50cb1d4 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:38:40 +0100 Subject: [PATCH 0099/1444] New translations crash-course.md (French) --- .../current/clarity/crash-course.md | 122 ++++++++++++++++++ 1 file changed, 122 insertions(+) create mode 100644 i18n/fr/docusaurus-plugin-content-docs/current/clarity/crash-course.md diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/clarity/crash-course.md b/i18n/fr/docusaurus-plugin-content-docs/current/clarity/crash-course.md new file mode 100644 index 0000000000..5b27a3c275 --- /dev/null +++ b/i18n/fr/docusaurus-plugin-content-docs/current/clarity/crash-course.md @@ -0,0 +1,122 @@ +--- +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.md). + +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. + +```clojure +(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: + +```clojure +(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. From 4f0b1b86efbf26a22a0b5a191dc37e73ac6ece8d Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:38:41 +0100 Subject: [PATCH 0100/1444] New translations sample-contracts.md (French) --- .../current/clarity/sample-contracts.md | 14 ++++++++++++++ 1 file changed, 14 insertions(+) create mode 100644 i18n/fr/docusaurus-plugin-content-docs/current/clarity/sample-contracts.md diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/clarity/sample-contracts.md b/i18n/fr/docusaurus-plugin-content-docs/current/clarity/sample-contracts.md new file mode 100644 index 0000000000..adb12a58fd --- /dev/null +++ b/i18n/fr/docusaurus-plugin-content-docs/current/clarity/sample-contracts.md @@ -0,0 +1,14 @@ +--- +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) From e24070354135cc404ecab933f2b1059a5b18d695 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:38:42 +0100 Subject: [PATCH 0101/1444] New translations index.md (French) --- .../current/cookbook/index.md | 64 +++++++++++++++++++ 1 file changed, 64 insertions(+) create mode 100644 i18n/fr/docusaurus-plugin-content-docs/current/cookbook/index.md diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/cookbook/index.md b/i18n/fr/docusaurus-plugin-content-docs/current/cookbook/index.md new file mode 100644 index 0000000000..a2b0e42eea --- /dev/null +++ b/i18n/fr/docusaurus-plugin-content-docs/current/cookbook/index.md @@ -0,0 +1,64 @@ +--- +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 + +Swapping between Bitcoin and Stacks addresses + +Swapping between xBTC and BTC + +Verifying a transaction on the BTC chain + +## 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 + +Airdropping an NFT to a Bitcoin address + +## Stacking and Mining + +Simple stacking pool + +Continuous stacking + +Simple mining pool + +Proof of PoX payout + +## Oracles + +Creating a simple BTC price oracle + +## Frontend + +[Post conditions with Stacks.js](./post-conditions) + +[Authentication with Stacks.js](./stacks-js-auth) + +[Sending transactions with Stacks.js](./stacks-js-sending-transactions) + +## Complete Apps + +[Sup](https://github.com/kenrogers/sup) + +[Hello Stacks](https://github.com/kenrogers/hello-stacks) From 6daea72063b3a0cf3112d83117fb3e8e04c3eb3b Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:38:43 +0100 Subject: [PATCH 0102/1444] New translations btc-connection.md (French) --- .../current/stacks-academy/btc-connection.md | 196 ++++++++++++++++++ 1 file changed, 196 insertions(+) create mode 100644 i18n/fr/docusaurus-plugin-content-docs/current/stacks-academy/btc-connection.md diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/stacks-academy/btc-connection.md b/i18n/fr/docusaurus-plugin-content-docs/current/stacks-academy/btc-connection.md new file mode 100644 index 0000000000..b4db915969 --- /dev/null +++ b/i18n/fr/docusaurus-plugin-content-docs/current/stacks-academy/btc-connection.md @@ -0,0 +1,196 @@ +--- +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. + +## Stacks Among Other Bitcoin Layers + +In the [last section](./what-is-stacks.md) we covered what Stacks actually is and what problem it is solving, but this is not a new problem. The Bitcoin write problem has been a bit of a holy grail problem in the crypto world for a while now. + +Bitcoin is the OG cryptocurrency and has the largest market cap, but it also some of the least functionality, which means if we want to make it a productive asset and use it to build a decentralized economy, we need to take a layered approach and let Bitcoin do what it does best, while creating additional layers on top of it to add functionality. + +So how does Stacks compare to some of the other approaches to layering on top of Bitcoin? + +### 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. + +## 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. + +But because it has its own execution environment and smart contract state to maintain, it needs a token to incentivize maintenance of the network. + +But it goes further than that. It is possible to build a system like this without a token using something like merge-mining or a sidechain, but then we lose out on the additional benefit of having the chain state's safety underpinned by its entire token economy's value. + +In the case of Stacks, the safety and liveness of the chain are underpinned by this value, and the stacking mechanism incentivizes network members to increase this value. + +From Jude Nelson, Stacks core developer: + +"How hard is it to cause a safety failure (i.e. a double-spend via a reorg) on just the canonical Stacks chain fork? Anyone can become a miner by spending BTC, so without loss of generality, reverting the last block on the canonical chain is at least as hard in expectation as spending more BTC than the rest of the miners combined for that block. Because each Bitcoin block selects at most one Stacks block, the act of reorging the canonical Stacks chain back N blocks is the act of winning at least N + 1 blocks built off of a common ancestor that is N blocks deep. This is a lower bound on the number of Bitcoin blocks mined during which a reorg needs to take place — in practice, honest miners will keep working on the canonical chain, and will win some Stacks blocks of their own, which in turn increases the number of Stacks blocks the reorging miners must win. + +How costly is it to carry out a reorg of N blocks? It’s a function of how valuable STX is relative to BTC — the more valuable STX are, the more BTC honest miners are committing to mining (this has borne out in practice), and thus the more BTC a reorging miner must commit. Therefore, the cost of a reorg is a function of the value of STX. + +This is similar to the economic security of a PoW blockchain. Like in PoW, each fork of the Stacks chain has its own independent “security budget” — an attacker must out-spend the security budget to carry out a reorg, and the security budget is a function of the block rewards. In PoX, the only difference is that the miners spend another blockchain’s tokens (BTC in Stacks’ case) instead of energy. Therefore, Stacks can’t be a sidechain, a drivechain, or a merge-mined chain, because none of these other systems’ security budgets are a function of their tokens’ worth. Sidechains, drivechains, and merged-mined chains all rely on external miners for their safety, since their safety is guaranteed in part by external miners validating their blocks. The onus on these systems is to get external miners to care enough to do so, and in the case of sidechains, drivechains, and blind merged-mined chains, there is an additional onus to encourage their nodes to mine blocks at all (since there is no on-chain reward for them to earn by doing so). By contrast, disinterested Bitcoin miners neither assist nor prevent a reorg in PoX — they only record the history of all Stacks forks. + +PoX offers two additional, unique security properties on top of PoW. First, no matter how much BTC a reorging miner can commit, the act of executing a reorg is going to be time-consuming. Unless the attacker can attack the Bitcoin chain itself by quickly producing a better Bitcoin fork, a reorging miner must sustain the attack for at least N + 1 Bitcoin blocks. This gives honest miners and users ample time to notice and react to the reorg attempt. + +Second, the history of block production in all Stacks forks is embedded within Bitcoin. This allows the system to leverage Bitcoin’s security budget in order to ensure that all forks are public. This is because the act of producing a hidden Stacks fork, where the fork’s block hashes are not known to the honest miners, is the act of producing a hidden canonical Bitcoin fork. Therefore, the act of producing a hidden Stacks fork is at least as hard as reorging the Bitcoin chain. A PoX chain leverages this property not to prevent reorgs, but to make reorgs unprofitable. + +By anchoring blocks to an existing blockchain, a PoX chain forces reorgs to happen out in the open, thereby giving advance warning to all honest network participants when they happen. Honest miners, users, and exchanges will see the PoX transactions for reorg attempts on the existing blockchain, and adapt their behaviors accordingly: honest miners will increase their commitments, and users and exchanges will require more confirmations for transactions. This makes the act of carrying out a reorg while also making a profit much more challenging, since malicious reorgs — like selfish mining and double-spending — rely on secrecy to work effectively. Specific to Stacks, miners are additionally required to mine for a “warm-up” period of two blocks, during which they must spend BTC at their target commit levels but will not win any Stacks blocks. So, a high-budget reorg attempt will not only be costly, but will also alert the rest of the network before the damage is done." + +- [What Kind of Blockchain is Stacks?](https://stacks.org/stacks-blockchain) + +## 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) From 028859ed0a76c7825df837c8ec68081bc972011b Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:38:44 +0100 Subject: [PATCH 0103/1444] New translations post-conditions.md (French) --- .../current/stacks-academy/post-conditions.md | 39 +++++++++++++++++++ 1 file changed, 39 insertions(+) create mode 100644 i18n/fr/docusaurus-plugin-content-docs/current/stacks-academy/post-conditions.md diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/stacks-academy/post-conditions.md b/i18n/fr/docusaurus-plugin-content-docs/current/stacks-academy/post-conditions.md new file mode 100644 index 0000000000..bb0727194f --- /dev/null +++ b/i18n/fr/docusaurus-plugin-content-docs/current/stacks-academy/post-conditions.md @@ -0,0 +1,39 @@ +--- +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). From 48980c7fa718e8a13db81cf7ff4af49de0b527fe Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:38:45 +0100 Subject: [PATCH 0104/1444] New translations creating-an-ft.md (French) --- .../current/cookbook/creating-an-ft.md | 99 +++++++++++++++++++ 1 file changed, 99 insertions(+) create mode 100644 i18n/fr/docusaurus-plugin-content-docs/current/cookbook/creating-an-ft.md diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/cookbook/creating-an-ft.md b/i18n/fr/docusaurus-plugin-content-docs/current/cookbook/creating-an-ft.md new file mode 100644 index 0000000000..4e3bad99d2 --- /dev/null +++ b/i18n/fr/docusaurus-plugin-content-docs/current/cookbook/creating-an-ft.md @@ -0,0 +1,99 @@ +--- +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) + ) +) +``` From d26745afb2f4cc7161a9e1cb86d8978df542b7ec Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:38:45 +0100 Subject: [PATCH 0105/1444] New translations creating-an-nft.md (French) --- .../current/cookbook/creating-an-nft.md | 87 +++++++++++++++++++ 1 file changed, 87 insertions(+) create mode 100644 i18n/fr/docusaurus-plugin-content-docs/current/cookbook/creating-an-nft.md diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/cookbook/creating-an-nft.md b/i18n/fr/docusaurus-plugin-content-docs/current/cookbook/creating-an-nft.md new file mode 100644 index 0000000000..08faf9393a --- /dev/null +++ b/i18n/fr/docusaurus-plugin-content-docs/current/cookbook/creating-an-nft.md @@ -0,0 +1,87 @@ +--- +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 +Code for this recipe has been pulled from [this NFT tutorial](https://blog.developerdao.com/building-an-nft-with-stacks-and-clarity) from Developer DAO. +::: + +## 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) + ) +) +``` From 53a5e82cf08f80dd53724641a7c58a867025076d Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:38:46 +0100 Subject: [PATCH 0106/1444] New translations post-conditions.md (French) --- .../current/cookbook/post-conditions.md | 136 ++++++++++++++++++ 1 file changed, 136 insertions(+) create mode 100644 i18n/fr/docusaurus-plugin-content-docs/current/cookbook/post-conditions.md diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/cookbook/post-conditions.md b/i18n/fr/docusaurus-plugin-content-docs/current/cookbook/post-conditions.md new file mode 100644 index 0000000000..571fc20d48 --- /dev/null +++ b/i18n/fr/docusaurus-plugin-content-docs/current/cookbook/post-conditions.md @@ -0,0 +1,136 @@ +--- +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. From e4480d3fdc64aa869c67d58833f95cc2489aef47 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:38:47 +0100 Subject: [PATCH 0107/1444] New translations stacks-js-auth.md (French) --- .../current/cookbook/stacks-js-auth.md | 98 +++++++++++++++++++ 1 file changed, 98 insertions(+) create mode 100644 i18n/fr/docusaurus-plugin-content-docs/current/cookbook/stacks-js-auth.md diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/cookbook/stacks-js-auth.md b/i18n/fr/docusaurus-plugin-content-docs/current/cookbook/stacks-js-auth.md new file mode 100644 index 0000000000..89d1f06e00 --- /dev/null +++ b/i18n/fr/docusaurus-plugin-content-docs/current/cookbook/stacks-js-auth.md @@ -0,0 +1,98 @@ +--- +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 && ( + + ); +} +``` From 341799e4c11687f6f793ecff542f664b4787883a Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:38:48 +0100 Subject: [PATCH 0108/1444] New translations stacks-js-sending-transactions.md (French) --- .../stacks-js-sending-transactions.md | 55 +++++++++++++++++++ 1 file changed, 55 insertions(+) create mode 100644 i18n/fr/docusaurus-plugin-content-docs/current/cookbook/stacks-js-sending-transactions.md diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/cookbook/stacks-js-sending-transactions.md b/i18n/fr/docusaurus-plugin-content-docs/current/cookbook/stacks-js-sending-transactions.md new file mode 100644 index 0000000000..849c7d1f42 --- /dev/null +++ b/i18n/fr/docusaurus-plugin-content-docs/current/cookbook/stacks-js-sending-transactions.md @@ -0,0 +1,55 @@ +--- +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. From 2455d24ac6b0555e749e1fb3b80367ada553564d Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:38:49 +0100 Subject: [PATCH 0109/1444] New translations _category_.json (French) --- .../current/clarity/noteworthy-contracts/_category_.json | 8 ++++++++ 1 file changed, 8 insertions(+) create mode 100644 i18n/fr/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/_category_.json diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/_category_.json b/i18n/fr/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/_category_.json new file mode 100644 index 0000000000..f5de305558 --- /dev/null +++ b/i18n/fr/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/_category_.json @@ -0,0 +1,8 @@ +{ + "label": "Noteworthy Contracts", + "position": 4, + "link": { + "type": "generated-index", + "description": "Specific deployed Clarity Contracts worth mentioning." + } +} \ No newline at end of file From 5f8dc873670d8797b0ca264901cc53beda77f439 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:38:50 +0100 Subject: [PATCH 0110/1444] New translations bns-contract.md (French) --- .../noteworthy-contracts/bns-contract.md | 519 ++++++++++++++++++ 1 file changed, 519 insertions(+) create mode 100644 i18n/fr/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/bns-contract.md diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/bns-contract.md b/i18n/fr/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/bns-contract.md new file mode 100644 index 0000000000..a7770b7d24 --- /dev/null +++ b/i18n/fr/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/bns-contract.md @@ -0,0 +1,519 @@ +--- +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 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` From 142321479b3cd3f18ee6fb21d09ef77e01ee171e Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:38:51 +0100 Subject: [PATCH 0111/1444] New translations xbtc.md (French) --- .../clarity/noteworthy-contracts/xbtc.md | 28 +++++++++++++++++++ 1 file changed, 28 insertions(+) create mode 100644 i18n/fr/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/xbtc.md diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/xbtc.md b/i18n/fr/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/xbtc.md new file mode 100644 index 0000000000..e535dcf260 --- /dev/null +++ b/i18n/fr/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/xbtc.md @@ -0,0 +1,28 @@ +--- +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) From cfe57405821e30c002692b3dc40510a4fcaf1a7b Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:38:52 +0100 Subject: [PATCH 0112/1444] New translations index.md (French) --- .../current/glossary/index.md | 284 ++++++++++++++++++ 1 file changed, 284 insertions(+) create mode 100644 i18n/fr/docusaurus-plugin-content-docs/current/glossary/index.md diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/glossary/index.md b/i18n/fr/docusaurus-plugin-content-docs/current/glossary/index.md new file mode 100644 index 0000000000..419c0e0d73 --- /dev/null +++ b/i18n/fr/docusaurus-plugin-content-docs/current/glossary/index.md @@ -0,0 +1,284 @@ +--- +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. From 5b795e8e5444fac2a98e669becf143323f6250db Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:38:52 +0100 Subject: [PATCH 0113/1444] New translations quicknode.md (French) --- .../current/nodes-and-miners/quicknode.md | 45 +++++++++++++++++++ 1 file changed, 45 insertions(+) create mode 100644 i18n/fr/docusaurus-plugin-content-docs/current/nodes-and-miners/quicknode.md diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/nodes-and-miners/quicknode.md b/i18n/fr/docusaurus-plugin-content-docs/current/nodes-and-miners/quicknode.md new file mode 100644 index 0000000000..1281964689 --- /dev/null +++ b/i18n/fr/docusaurus-plugin-content-docs/current/nodes-and-miners/quicknode.md @@ -0,0 +1,45 @@ +--- +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. From 0a71a6945908ff3e53e55c9050fe5de08296dee3 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:38:53 +0100 Subject: [PATCH 0114/1444] New translations defi.md (French) --- .../current/services-using-stacks/defi.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) 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 index 51defacba7..58717a3234 100644 --- 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 @@ -26,7 +26,7 @@ Please edit this page to add any relevant new site that we are missing. ## Lnswap -[LNSWAP](https://www.lnswap.org). Non custiodial crypto currency exchange +[LNSWAP](https://www.lnswap.org). Non-custodial crypto currency exchange ![](/img/sh_lnswap.png) @@ -41,4 +41,3 @@ Please edit this page to add any relevant new site that we are missing. [Stackswap](https://app.stackswap.org/v2) ![](/img/sh_stackswap.png) - From 133f146730d633ef25929b1709126c20eba7511f Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:38:54 +0100 Subject: [PATCH 0115/1444] New translations more.md (French) --- .../current/services-using-stacks/more.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) 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 index df0b3e2254..1e14b9a5a5 100644 --- 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 @@ -18,6 +18,6 @@ Please edit this page to add any relevant new site that we are missing. ## Sigle -[Sigle](https://www.sigle.io/) is a decentralised and open source web 3 writing platform. +[Sigle](https://www.sigle.io/) is a decentralized and open source web 3 writing platform. -![](/img/sh_sigle.png) \ No newline at end of file +![](/img/sh_sigle.png) From 609a152bb25335cfa532755cc0167231680fe6ea Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:38:55 +0100 Subject: [PATCH 0116/1444] New translations nft.md (French) --- .../current/services-using-stacks/nft.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) 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 index abb770663c..d582604854 100644 --- 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 @@ -15,6 +15,7 @@ Please edit this page to add any relevant new site that we are missing. ![website-screenshot](/img/sh_nft_byzantion.png) ### [Gamma](https://gamma.io/) + ![website-screenshot](/img/sh_nft_gamma.png) ### [Megapont](https://www.megapont.com/) @@ -35,4 +36,4 @@ Please edit this page to add any relevant new site that we are missing. ### [Superfandom](https://superfandom.io/) -![website-screenshot](/img/sh_superfandom.png) \ No newline at end of file +![website-screenshot](/img/sh_superfandom.png) From 5344cdab4ca43a2afba536d4ef2da1961ce07f49 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:38:56 +0100 Subject: [PATCH 0117/1444] New translations stacks-info-sites.md (French) --- .../current/services-using-stacks/stacks-info-sites.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) 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 index 35ced8dac6..54f6823e33 100644 --- 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 @@ -30,7 +30,7 @@ Please edit this page to add any relevant new site that we are missing. ![website-screenshot](/img/sh_stxstats.png) -### [Novuminsights](https://stacks.novuminsights.com/health) +### [Novum Insights](https://stacks.novuminsights.com/health) ![website-screenshot](/img/sh_novuminsights.png) From efd9c3ba152bbf37c7da56cd353652e2a924a1d9 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:38:56 +0100 Subject: [PATCH 0118/1444] New translations wallets.md (French) --- .../current/services-using-stacks/wallets.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) 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 index e5ea6c5b45..2d3fcc85f2 100644 --- 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 @@ -15,6 +15,7 @@ Please edit this page to add any relevant new site that we are missing. [Blockchain.com](https://www.blockchain.com/wallet) ![](/img/sh_blockchain.png) + ## Boom [Boom](https://boom.money) @@ -26,6 +27,7 @@ Please edit this page to add any relevant new site that we are missing. [D'CENT](https://dcentwallet.com) ![](/img/sh_dcent.png) + ## Hiro Wallet [Hiro Wallet](https://www.hiro.so/wallet) @@ -48,4 +50,4 @@ Please edit this page to add any relevant new site that we are missing. [Wise](https://wiseapp.id) -![](/img/sh_wiseapp.png) \ No newline at end of file +![](/img/sh_wiseapp.png) From cab039acf8de42d27cb582c343e2111c8ef8facc Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:38:57 +0100 Subject: [PATCH 0119/1444] New translations whitepapers.md (French) --- .../current/stacks-academy/whitepapers.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) create mode 100644 i18n/fr/docusaurus-plugin-content-docs/current/stacks-academy/whitepapers.md diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/stacks-academy/whitepapers.md b/i18n/fr/docusaurus-plugin-content-docs/current/stacks-academy/whitepapers.md new file mode 100644 index 0000000000..0e564fbf44 --- /dev/null +++ b/i18n/fr/docusaurus-plugin-content-docs/current/stacks-academy/whitepapers.md @@ -0,0 +1,12 @@ +--- +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) From 81a2578bc7bf55722fafdee5359da7cdeb8aad12 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:38:58 +0100 Subject: [PATCH 0120/1444] New translations stacking-contract.md (French) --- .../noteworthy-contracts/stacking-contract.md | 352 ++++++++++++++++++ 1 file changed, 352 insertions(+) create mode 100644 i18n/fr/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/stacking-contract.md diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/stacking-contract.md b/i18n/fr/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/stacking-contract.md new file mode 100644 index 0000000000..c0027256cd --- /dev/null +++ b/i18n/fr/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/stacking-contract.md @@ -0,0 +1,352 @@ +--- +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. 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` From 230a15f4e3d051e09d3f9c30914699f2716a3dbc Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:38:59 +0100 Subject: [PATCH 0121/1444] New translations index.md (French) --- .../current/next-steps/index.md | 39 +++++++++++++++++++ 1 file changed, 39 insertions(+) create mode 100644 i18n/fr/docusaurus-plugin-content-docs/current/next-steps/index.md diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/next-steps/index.md b/i18n/fr/docusaurus-plugin-content-docs/current/next-steps/index.md new file mode 100644 index 0000000000..00ddec9178 --- /dev/null +++ b/i18n/fr/docusaurus-plugin-content-docs/current/next-steps/index.md @@ -0,0 +1,39 @@ +--- +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) From 958cca9b56527ba5b1edf1ef62f931f5e5654732 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:39:00 +0100 Subject: [PATCH 0122/1444] New translations sips.md (French) --- .../current/stacks-academy/sips.md | 52 +++++++++++++++++++ 1 file changed, 52 insertions(+) create mode 100644 i18n/fr/docusaurus-plugin-content-docs/current/stacks-academy/sips.md diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/stacks-academy/sips.md b/i18n/fr/docusaurus-plugin-content-docs/current/stacks-academy/sips.md new file mode 100644 index 0000000000..aa2db18e62 --- /dev/null +++ b/i18n/fr/docusaurus-plugin-content-docs/current/stacks-academy/sips.md @@ -0,0 +1,52 @@ +--- +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/IJ15791776) 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-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. From 5ea90cbcbf12d3a05ccda95770485615952fbd6b Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:39:01 +0100 Subject: [PATCH 0123/1444] New translations hosted-nodes.md (French) --- .../current/nodes-and-miners/hosted-nodes.md | 25 +++++++++++++++++++ 1 file changed, 25 insertions(+) create mode 100644 i18n/fr/docusaurus-plugin-content-docs/current/nodes-and-miners/hosted-nodes.md diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/nodes-and-miners/hosted-nodes.md b/i18n/fr/docusaurus-plugin-content-docs/current/nodes-and-miners/hosted-nodes.md new file mode 100644 index 0000000000..12d86c7ee2 --- /dev/null +++ b/i18n/fr/docusaurus-plugin-content-docs/current/nodes-and-miners/hosted-nodes.md @@ -0,0 +1,25 @@ +--- +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. From 6f5abda388f111a067953fe7a50e248b16c9f9db Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:39:02 +0100 Subject: [PATCH 0124/1444] New translations authentication.md (Spanish) --- .../current/stacks-academy/authentication.md | 63 +++++++++++++++++++ 1 file changed, 63 insertions(+) create mode 100644 i18n/es/docusaurus-plugin-content-docs/current/stacks-academy/authentication.md diff --git a/i18n/es/docusaurus-plugin-content-docs/current/stacks-academy/authentication.md b/i18n/es/docusaurus-plugin-content-docs/current/stacks-academy/authentication.md new file mode 100644 index 0000000000..cefd1b2907 --- /dev/null +++ b/i18n/es/docusaurus-plugin-content-docs/current/stacks-academy/authentication.md @@ -0,0 +1,63 @@ +--- +title: Autenticación +description: Registrar e iniciar sesión de usuarios con identidades en la blockchain de Stacks +sidebar_position: 8 +--- + +## 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. From 1d3f14d50a9b207189198752a4cefdbb18c30a24 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:39:04 +0100 Subject: [PATCH 0125/1444] New translations bns.md (Spanish) --- .../current/stacks-academy/bns.md | 245 ++++++++++++++++++ 1 file changed, 245 insertions(+) create mode 100644 i18n/es/docusaurus-plugin-content-docs/current/stacks-academy/bns.md diff --git a/i18n/es/docusaurus-plugin-content-docs/current/stacks-academy/bns.md b/i18n/es/docusaurus-plugin-content-docs/current/stacks-academy/bns.md new file mode 100644 index 0000000000..30b43ca760 --- /dev/null +++ b/i18n/es/docusaurus-plugin-content-docs/current/stacks-academy/bns.md @@ -0,0 +1,245 @@ +--- +title: Sistema de Nombres de Blockchain +description: Vincula los nombres de usuario de Stacks al estado off-chain +sidebar_position: 8 +--- + +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. 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). + +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). From 86ac9d691136b888078de9e7889ad1d65d08df70 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:39:05 +0100 Subject: [PATCH 0126/1444] New translations docs.md (Spanish) --- .../current/contribute/docs.md | 24 ++++++++++++------- 1 file changed, 15 insertions(+), 9 deletions(-) diff --git a/i18n/es/docusaurus-plugin-content-docs/current/contribute/docs.md b/i18n/es/docusaurus-plugin-content-docs/current/contribute/docs.md index d28e84d26c..afd2fd65af 100644 --- a/i18n/es/docusaurus-plugin-content-docs/current/contribute/docs.md +++ b/i18n/es/docusaurus-plugin-content-docs/current/contribute/docs.md @@ -7,7 +7,7 @@ description: Aprende cómo se construye este sitio y cómo puedes contribuir a 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). +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. 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. @@ -15,7 +15,7 @@ Este sitio de documentación está construido en la plataforma de código abiert :::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. +To edit any page, just click on the _Edit this page_ button at the bottom of each page and submit your changes online. Para añadir nuevo contenido, existen dos formas diferentes de hacerlo, la [forma fácil](#easy-way) y la [forma avanzada](#advanced-way). @@ -24,28 +24,32 @@ Para añadir nuevo contenido, existen dos formas diferentes de hacerlo, la [form [**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. +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. 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. + - `npm install` (para instalar dependencias). + - `npx docusaurus start` para iniciar una copia local del sitio. A web browser will open at http://localhost:3000, so you can see a preview of your changes in real time. 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 +## Additional information + ### 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 ``` @@ -54,8 +58,8 @@ Antes de ejecutar este comando por primera vez, debes de ejecutar `npm install` 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 ``` @@ -91,7 +95,7 @@ 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. +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 @@ -124,6 +128,7 @@ And execute prettier with the following command: npx prettier --write mynewfiletocheck.md ``` --> + ### 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. @@ -138,6 +143,7 @@ Para escribir un bloque de código, necesitas envolver tu código en ` ```langua (define-public (get-counter) (ok (var-get counter))) ``` + ### Avisos Puede utilizar los siguientes avisos para resaltar el contenido. @@ -204,4 +210,4 @@ Algo de **contenido** con `syntax` markdown. Algo de **contenido** con `syntax` markdown. -::: \ No newline at end of file +::: From e0d5fec3fb24f414966d833a7a8aa4a8c2580efc Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:39:06 +0100 Subject: [PATCH 0127/1444] New translations translations.md (Spanish) --- .../current/contribute/translations.md | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/i18n/es/docusaurus-plugin-content-docs/current/contribute/translations.md b/i18n/es/docusaurus-plugin-content-docs/current/contribute/translations.md index 0391e7e386..b31b326c31 100644 --- a/i18n/es/docusaurus-plugin-content-docs/current/contribute/translations.md +++ b/i18n/es/docusaurus-plugin-content-docs/current/contribute/translations.md @@ -1,25 +1,24 @@ --- title: Contribuye en la traducción -description: '¿Quieres ayudar a traducir la documentación a tu propio idioma?' +description: Want to help translating these docs to your local language? --- ## 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. +Translations are managed with Crowdin. Anybody can collaborate and no technical skills are required, as it's all done on the browser. 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. +Por favor, no añadas ninguna traducción al repositorio de Github, ya que las páginas traducidas son reescritas desde Crowdin. Translations need to be added on Crowdin instead. ::: ### 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. +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`). 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) From 17c1df816c5b52b8b0e91bfd4b7147fb081c1446 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:39:08 +0100 Subject: [PATCH 0128/1444] New translations gaia-on-ec2.md (Spanish) --- .../current/gaia/gaia-on-ec2.md | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) 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 index e938409343..4bc5111559 100644 --- 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 @@ -26,9 +26,10 @@ Utilice un enlace en la tabla para lanzar la plantilla [CloudFormation](https:// ### 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. +You need to configure the template with the appropriate values for your hub and domain it runs on. 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 ``` @@ -52,7 +53,7 @@ Especifique los detalles de stacks y luego haga clic en `Next`: ![Especificar pl | 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`. | +| InstanceType | 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 | @@ -93,7 +94,9 @@ ssh -i admin@ 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 +![](/img/cloudformation-gaia-template1-designer.png) From 128a79f6bc2edf117e3f1ce166e5df800f8a5e43 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:39:09 +0100 Subject: [PATCH 0129/1444] New translations gaia.md (Spanish) --- .../current/gaia/gaia.md | 12 +++++++++--- 1 file changed, 9 insertions(+), 3 deletions(-) diff --git a/i18n/es/docusaurus-plugin-content-docs/current/gaia/gaia.md b/i18n/es/docusaurus-plugin-content-docs/current/gaia/gaia.md index 908fe80039..5352be6c51 100644 --- a/i18n/es/docusaurus-plugin-content-docs/current/gaia/gaia.md +++ b/i18n/es/docusaurus-plugin-content-docs/current/gaia/gaia.md @@ -1,14 +1,20 @@ --- title: Gaia description: Arquitectura de almacenamiento descentralizado para datos fuera de la cadena -sidebar_position: 5 +sidebar_position: 6 tags: - gaia --- ## Introducción -Las aplicaciones construidas en la blockchain de Stacks almacenan datos fuera de cadena usando un sistema de almacenamiento llamado Gaia. +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. 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. @@ -38,7 +44,7 @@ La blockchain de Stacks almacena sólo datos de identidad. Los datos creados por 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) +![Gai storage](/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. From f680f56b3d4819f69c216922053d29d29568e47f Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:39:10 +0100 Subject: [PATCH 0130/1444] New translations setup-linux.md (Spanish) --- .../current/gaia/setup-linux.md | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) 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 index f98f5b84e3..433d1de79d 100644 --- a/i18n/es/docusaurus-plugin-content-docs/current/gaia/setup-linux.md +++ b/i18n/es/docusaurus-plugin-content-docs/current/gaia/setup-linux.md @@ -1,6 +1,6 @@ --- 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. +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. It uses docker compose in the background. tags: - tutorial - gaia @@ -19,8 +19,7 @@ Esta configuración configurará los siguientes 4 contenedores docker: 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: +**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 @@ -48,8 +47,7 @@ chmod +x ${DESTINATION_DC}/docker-compose 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. +**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. 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 From a94f9c9e995a1b2e368f259887dd1b6b303aec93 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:39:12 +0100 Subject: [PATCH 0131/1444] New translations index.md (Spanish) --- .../current/nodes-and-miners/index.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) 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 index f25944c2c5..8cdc5506da 100644 --- 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 @@ -1,11 +1,11 @@ --- title: Nodos y Mineros description: Nodos y Mineros -sidebar_position: 7 +sidebar_position: 5 --- -Aquí están todos los pasos para ejecutar nodos y mineros, tanto en mainnet como en testnet. +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. -## ¿Qué es un nodo de Stacks? +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. -## ¿Qué es un minero de Stacks? +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. From 9fe266b6e455c5a413a884fde6633ac05c8bd936 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:39:13 +0100 Subject: [PATCH 0132/1444] New translations miner-mainnet.md (Spanish) --- .../current/nodes-and-miners/miner-mainnet.md | 301 +++++++----------- 1 file changed, 110 insertions(+), 191 deletions(-) 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 index 3c74e8bd03..1fce8a27a6 100644 --- 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 @@ -1,166 +1,100 @@ --- title: Mine mainnet Stacks tokens -description: Set up and run a miner on the Stacks 2.0 mainnet -sidebar_position: 5 +description: Set up and run a miner on Stacks Mainnet +sidebar_position: 6 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. +For more on the technical details of mining, please review the [mining guide](../stacks-academy/mining) -If you're interested in mining on the testnet, you can find instructions on how to do that [here](miner-testnet): +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 want to learn more about the technical details of mining, please review the [mining guide](../understand-stacks/mining): +If you're interested in mining on the Stacks testnet, you can find instructions on how to do that [here](miner-testnet): -## Running bitcoind locally +## Running a Bitcoin Mainnet Full Node -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) +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. -First, download the bitcoind software for your platform from https://bitcoin.org/en/download. +- [Ensure your computer meets the minimum hardware requirements before continuing.](https://bitcoin.org/en/bitcoin-core/features/requirements#system-requirements) -Next, start bitcoind with the following configuration: +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): -```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 -``` +:::tip It is recommened to use a persistent location for the chainstate, in the steps below we're using `/bitcoin` ::: -Finally, start bitcoind as follows: +### Update the Bitcoin Configuration File -```bash -bitcoind -conf=path/to/bitcoin.conf -``` - -It may take a few days for the node to synchronize with the Bitcoin mainnet. +Next, update the bitcoin configuration: -## 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: +- **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 -[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 = "" -... +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 ``` -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. +### Start Bitcoin -To run your miner, run this in the command line: +Finally, start bitcoin as follows (adjust the `conf` path to where it was created in the previous step, i.e. `$HOME/bitcoin.conf`): ```bash -stacks-node start --config=./testnet/stacks-node/conf/mainnet-miner-conf.toml +bitcoind -conf=$HOME/bitcoin.conf ``` -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 -``` +:::note +It will take a few days for the node to synchronize with Bitcoin mainnet. +::: -The above code will compile an optimized binary. To use it, run: +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 -cd ../.. -./target/release/stacks-node start --config=./mainnet-miner-conf.toml +$ bitcoin-cli \ + -rpcconnect=localhost \ + -rpcport=8332 \ + -rpcuser=btcuser \ + -rpcpassword=btcpassword \ +getblockchaininfo | jq .blocks +773281 ``` -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 Stacks Blockchain miner -## Running a miner in Windows +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) -### Pre requisitos +_There may be some extra requirements to building, [defined here](https://github.com/stacksfoundation/miner-docs/blob/main/prerequisites.md#install-required-packages)_ -Make sure are [running a node](run-a-node) and [running bitcoind locally](#running-bitcoind-locally) before starting this tutorial. +:::tip It is recommened to use a persistent location for the chainstate, in the steps below we're using `/stacks-blockchain` ::: -### Generate keychain and get mainnet tokens in Windows +### Generate a keychain -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 cryptocurrency 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: +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 -npm install --global @stacks/cli -stx make_keychain > cli_keychain.json -type cli_keychain.json +npx @stacks/cli make_keychain 2>/dev/null | jq -r ``` -After this runs, you'll probably see some installation logs, and at the end you should see some JSON that looks like this: +After this runs, you should see some JSON printed to the screen that looks like this: ```json { @@ -174,109 +108,99 @@ After this runs, you'll probably see some installation logs, and at the end you } ``` -:::tip Check out the [Stacks CLI reference](https://docs.hiro.so/references/stacks-cli) for more details ::: +:::warning **Do not lose this information** - we'll need to use the `privateKey` and `btcAddress` fields in later steps. ::: -The above BTC address will then need to be imported into the BTC network. +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=your-user -rpcpassword=your-password importaddress +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 configuration file + + +### Update the Stacks Blockchain 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). +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`. -Update the following properties: +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] -... -# Enter your private key here -seed = "replace-with-your-private-key" -local_peer_seed = "replace-with-your-private-key" -... +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] -... -# To mine on mainnet, you need to run bitcoind locally -# Details can be found in above section, 'Running bitcoind locally' +chain = "bitcoin" +mode = "mainnet" peer_host = "127.0.0.1" -username = "" -password = "" -... +username = "" +password = "" +rpc_port = 8332 +peer_port = 8333 +satoshis_per_byte = 100 +burn_fee_cap = 20000 ``` -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 +### Start the Stacks Blockchain -To start your miner, run this in the command line: +To run your miner, run this in the command line: ```bash -stacks-node start --config=testnet/stacks-node/conf/mainnet-miner-conf.toml +stacks-node start --config=$HOME/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 +### 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 -set RUST_BACKTRACE=full; -set STACKS_LOG_DEBUG=1; -stacks-node start --config=mainnet-miner-conf.toml +STACKS_LOG_DEBUG=1 stacks-node start --config=$HOME/mainnet-miner-conf.toml ``` -## Optional: Running with Docker +--- + +## Optional: Running a Stacks Blockchain miner with Docker -Alternatively, you can run the mainnet node with Docker. +Alternatively, you can run a Stacks mainnet miner with Docker. -:::caution Ensure you have [Docker](https://docs.docker.com/get-docker/) installed on your machine. ::: +:::caution Ensure you have [Docker](https://docs.docker.com/get-docker/) installed. ::: -### Generate keychain and get tokens +### 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 +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 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: +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). -```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 = "" -... -``` +### Update Stacks Blockchain Docker Configuration File -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. +Use the steps oulined above to create the [configuration file](miner-mainnet#update-the-stacks-blockchain-configuration-file) -### Start the miner +### 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 ::: @@ -287,7 +211,8 @@ docker run -d \ --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" \ + -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 \ @@ -302,9 +227,9 @@ 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). +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 on your machine: +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) @@ -313,13 +238,7 @@ Ensure you have the following prerequisites installed on your machine: ### 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). +Use the steps [outlined above](miner-mainnet#generate-a-keychain-and-get-some-tokens) ### Install the chart and run the miner From c7e2a6e9f3a62aad3e9474860ed7a1b87d214e76 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:39:14 +0100 Subject: [PATCH 0133/1444] New translations miner-testnet.md (Spanish) --- .../current/nodes-and-miners/miner-testnet.md | 318 +++++++----------- 1 file changed, 130 insertions(+), 188 deletions(-) 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 index f1a8345c66..510246467c 100644 --- 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 @@ -1,35 +1,52 @@ --- title: Mine testnet Stacks tokens -description: Set up and run a miner on the Stacks 2.0 testnet -sidebar_position: 4 +description: Set up and run a miner on Stacks Testnet +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 testnet. +For more on the technical details of mining, please review the [mining guide](../stacks-academy/mining) -If you want to learn more about the technical details of mining, please review the [mining guide](../understand-stacks/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)). -## Running bitcoind locally +If you're interested in mining on the Stacks mainnet, you can find instructions on how to do that [here](miner-mainnet): -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) +## Running a Bitcoin Testnet Full Node -First, download the bitcoind software for your platform from https://bitcoin.org/en/download. +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. -Next, start bitcoind with the following configuration: +- [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 -rpcuser=your-bitcoind-username -rpcpassword=your-bitcoind-password testnet=1 -txindex=0 -listen=1 -rpcserialversion=0 -maxorphantx=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 @@ -37,126 +54,51 @@ 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" -... +### Start Bitcoin -[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: +Finally, start bitcoind as follows: ```bash -stacks-node start --config=./testnet/stacks-node/conf/testnet-miner-conf.toml +bitcoind -conf=$HOME/bitcoin.conf ``` -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 -``` +:::note +It will take a few hours for the node to synchronize with Bitcoin testnet. +::: -The above code will compile an optimized binary. To use it, run: +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 -cd ../.. -./target/release/stacks-node start --config=./testnet/conf/testnet-follower-conf.toml +$ bitcoin-cli \ + -rpcconnect=localhost \ + -rpcport=18332 \ + -rpcuser=btcuser \ + -rpcpassword=btcpass \ +getblockchaininfo | jq .blocks +2417570 ``` -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 +## Running a Stacks Blockchain miner -### Pre requisitos +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) -Make sure are [running a testnet node](run-a-node) before starting this tutorial. +_There may be some extra requirements to building, [defined here](https://github.com/stacksfoundation/miner-docs/blob/main/prerequisites.md#install-required-packages)_ -### Generate keychain and get testnet tokens in Windows +:::tip It is recommened to use a persistent location for the chainstate, in the steps below we're using `/stacks-blockchain` ::: -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. +### Generate a keychain -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. +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. -Generate a keychain: +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 -npm install --global @stacks/cli -stx make_keychain -t > cli_keychain.json -type cli_keychain.json +npx @stacks/cli make_keychain -t 2>/dev/null | jq -r ``` -After this runs, you'll probably see some installation logs, and at the end you should see some JSON that looks like this: +After this runs, you should see some JSON printed to the screen that looks like this: ```json { @@ -170,107 +112,110 @@ After this runs, you'll probably see some installation logs, and at the end you } ``` -:::tip Check out the [Stacks CLI reference](https://docs.hiro.so/references/stacks-cli) for more details ::: +:::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. -Request BTC from faucet: +### Update the Stacks Blockchain Configuration File -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/). +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`. -### Update configuration file +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. -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). +Next, update the bitcoin configuration: -Update the following properties: +- **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] -... -seed = "replace-with-your-private-key" -local_peer_seed = "replace-with-your-private-key" -... +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] -... -# To mine on Testnet, you need to run bitcoind locally -# Details can be found in above section, 'Running bitcoind locally' +chain = "bitcoin" +mode = "xenon" peer_host = "127.0.0.1" -username = "" -password = "" -... +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 ``` -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 +### Start the Stacks Blockchain -To start your miner, run this in the command line: +To run your miner, run this in the command line: ```bash -stacks-node start --config=testnet/stacks-node/conf/testnet-miner-conf.toml +stacks-node start --config=$HOME/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 +### 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 -set RUST_BACKTRACE=full; -set STACKS_LOG_DEBUG=1; -stacks-node start --config=testnet-miner-conf.toml +STACKS_LOG_DEBUG=1 stacks-node start --config=$HOME/testnet-miner-conf.toml ``` -## Optional: Running with Docker +--- + +## Optional: Running a Stacks Blockchain miner with Docker -Alternatively, you can run the testnet node with Docker. +Alternatively, you can run a Stacks testnet miner with Docker. -:::warning Ensure you have [Docker](https://docs.docker.com/get-docker/) installed on your machine. ::: +:::caution Ensure you have [Docker](https://docs.docker.com/get-docker/) installed ::: -### Generate keychain and get testnet tokens +### Generate a Keychain and Get Some Tokens Generate a keychain: ```bash -docker run -i node:14-alpine npx @stacks/cli make_keychain -t 2>/dev/null +docker run -i node:14-alpine npx @stacks/cli make_keychain 2>/dev/null | jq -r ``` -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 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. -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 Stacks Blockchain Docker Configuration File -Update the following properties: +Use the steps oulined above to create the [configuration file](miner-testnet#update-the-stacks-blockchain-configuration-file) -```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 +### 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 ::: @@ -281,7 +226,8 @@ docker run -d \ --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" \ + -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 \ @@ -294,26 +240,22 @@ You can review the node logs with this command: 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). +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 on your machine: +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 testnet tokens - -Generate a keychain: - -```bash -docker run -i node:14-alpine npx @stacks/cli make_keychain -t 2>/dev/null -``` +### Generate keychain and get some tokens -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/). +Use the steps [outlined above](miner-testnet#generate-a-keychain-and-get-some-tokens) ### Install the chart and run the miner @@ -324,7 +266,7 @@ 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.node.seed="replace-with-your-privateKey-from-generate-keychain-step" \ ``` You can review the node logs with this command: From 4723e20cdee6135c13a06b214ff108915570eeea Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:39:15 +0100 Subject: [PATCH 0134/1444] New translations stacks-node-configuration.md (Spanish) --- .../stacks-node-configuration.md | 232 +++++++++++------- 1 file changed, 138 insertions(+), 94 deletions(-) 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 index ea61c808e0..fe42ce8478 100644 --- 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 @@ -1,7 +1,7 @@ --- title: Configuración del nodo de Stacks description: Parámetros de configuración y opciones para el binario stacks-node -sidebar_position: 6 +sidebar_position: 4 --- ## Uso @@ -10,97 +10,141 @@ sidebar_position: 6 stacks-node sub-command [--subcommand-option ] ``` -## Subcomandos +### Subcommands -:::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 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 -### mocknet +## Opciones de configuración -Start a node based on a fast local setup emulating a burnchain. Ideal for smart contract development. +The Stacks Blockchain configuration file has multiple sections under which an option may be placed. -Ejemplo: +- [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) -```bash -stacks-node mocknet -``` +For reference, several configuration file examples are [available here](https://github.com/stacks-network/stacks-blockchain/tree/master/testnet/stacks-node/conf) -### krypton +- [Example mainnet follower configuration](./stacks-node-configuration#example-mainnet-follower-configuration) -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). +### node -Ejemplo: +Contains various configuration options for the stacks-node binary. -```bash -stacks-node krypton -``` +| Name | Required | Descripción | +| --------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------- | +| 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. | -### testnet +### events_observer -Start a node that will join and stream blocks from the public testnet. +:::info This section is _optional_ and not required -Ejemplo: +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. -```bash -stacks-node testnet -``` +| Name | Required | Descripción | +| ----------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| 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. | | -### mainnet +### connection_options -Start a node that joins and streams blocks from the public mainnet. +:::info This section is _optional_ and not required. -Ejemplo: +However, if this section is added, **all** fields are required ::: -```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. +Specifies configuration options for others connecting to the stacks node. -#### Argumentos +| Name | Required | Descripción | +| ------------------------------------ | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | +| 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 | -**--config**: relative or absolute path to the TOML config file. Required. +### burnchain -Ejemplo: +This section contains configuration options pertaining to the blockchain the stacks-node binds to on the backend for proof-of-transfer (BTC). -```bash -stacks-node start --config=/path/to/config.toml -``` +| Name | Required | Descripción | +| --------- | -------- | -------------------------------------------------------------------------------------------------------------------- | +| 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` | -See [Configuration File Options](#configuration-file-options) for more information. +#### Minería -#### version +| Name | Required | Descripción | +| ---------------------------- | -------- | -------------------------------------------------------------------------------------------------- | +| 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`. | -Muestra información sobre la versión actual y el ciclo de lanzamiento. +### ustx_balance -Ejemplo: +- `mocknet`/`testnet` only -```bash -stacks-node version -``` +This section contains configuration options allocating microSTX per address in the genesis block -#### help +This section can repeat multiple times, but each section can only define a single address. -Muestra un mensaje de ayuda. +:::info This section is only required for the `testnet` and `mocknet` networks. -Ejemplo: +However, if this section is added, **all** fields are required ::: -```bash -stacks-node help -``` +| Name | Required | Descripción | +| ------- | -------- | --------------------------------------------------------------------- | +| address | ✓ | Address which maintains a microSTX balance | +| amount | ✓ | The balance of microSTX given to the address at the start of the node | -## Opciones de configuración +## Example Mainnet Follower Configuration -The TOML configuration file has multiple sections under which an option may be placed. +```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" -To see a list of example configurations, [please see this page](https://github.com/stacks-network/stacks-blockchain/tree/master/testnet/stacks-node/conf). +[burnchain] +chain = "bitcoin" +mode = "mainnet" +peer_host = "localhost" +username = "user" +password = "pass" +rpc_port = 8332 +peer_port = 8333 -### Sección: node +[[events_observer]] +endpoint = "localhost:3700" +retry_count = 255 +events_keys = ["*"] +``` -Contains various configuration options pertaining to the stacks-node. -Ejemplo: + From 0ad2177ab0c09cb10d5c5c2c38b44622ae1fb4b3 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:39:16 +0100 Subject: [PATCH 0135/1444] New translations accounts.md (Spanish) --- .../current/stacks-academy/accounts.md | 215 ++++++++++++++++++ 1 file changed, 215 insertions(+) create mode 100644 i18n/es/docusaurus-plugin-content-docs/current/stacks-academy/accounts.md diff --git a/i18n/es/docusaurus-plugin-content-docs/current/stacks-academy/accounts.md b/i18n/es/docusaurus-plugin-content-docs/current/stacks-academy/accounts.md new file mode 100644 index 0000000000..21a4d17ac4 --- /dev/null +++ b/i18n/es/docusaurus-plugin-content-docs/current/stacks-academy/accounts.md @@ -0,0 +1,215 @@ +--- +title: Cuentas +description: Guía de cuentas de Stacks 2.0 +sidebar_position: 7 +--- + +## 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. No person or organization can recover a lost seed phrase. +::: + +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, + 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 +); +``` + +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" + } + } + ] +} +``` From 5716de7b62aa6d04f4a725619dcbfcfcbccd436b Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:39:17 +0100 Subject: [PATCH 0136/1444] New translations microblocks.md (Spanish) --- .../current/stacks-academy/microblocks.md | 107 ++++++++++++++++++ 1 file changed, 107 insertions(+) create mode 100644 i18n/es/docusaurus-plugin-content-docs/current/stacks-academy/microblocks.md diff --git a/i18n/es/docusaurus-plugin-content-docs/current/stacks-academy/microblocks.md b/i18n/es/docusaurus-plugin-content-docs/current/stacks-academy/microblocks.md new file mode 100644 index 0000000000..39e1503af5 --- /dev/null +++ b/i18n/es/docusaurus-plugin-content-docs/current/stacks-academy/microblocks.md @@ -0,0 +1,107 @@ +--- +title: Microbloques +description: Guía de Microbloques Stacks +sidebar_position: 5 +--- + +## Introducción + +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. + +## Estados de la transacción + +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: + +``` +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. +... +``` + +Consider a similar transaction that is not included in a microblock: + +``` +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. +``` + +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. +::: + +## Habilitar microbloques + +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. + +### Transacciones + +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. + +### Minería + +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). + +## Desarrollando con microbloques + +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. + +## Buenas prácticas + +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. + +### Manejo de 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. + +### Diseño de aplicación + +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. + +#### Exploradores + +Display pending state, but warn that a transaction is still pending. Indicate visually that displayed balances depend on pending state. + +#### Billeteras + +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. + +#### Aplicaciones + +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. + +[provides an endpoint]: https://docs.hiro.so/get-started/stacks-blockchain-api#nonce-handling +[microblocks_api]: https://docs.hiro.so/api#tag/Microblocks From 323b2e9dc0947720a50f68d930a31fd2fe38e06e Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:39:18 +0100 Subject: [PATCH 0137/1444] New translations mining.md (Spanish) --- .../current/stacks-academy/mining.md | 84 +++++++++++++++++++ 1 file changed, 84 insertions(+) create mode 100644 i18n/es/docusaurus-plugin-content-docs/current/stacks-academy/mining.md diff --git a/i18n/es/docusaurus-plugin-content-docs/current/stacks-academy/mining.md b/i18n/es/docusaurus-plugin-content-docs/current/stacks-academy/mining.md new file mode 100644 index 0000000000..2764c660dd --- /dev/null +++ b/i18n/es/docusaurus-plugin-content-docs/current/stacks-academy/mining.md @@ -0,0 +1,84 @@ +--- +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. + +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). + +## 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) + +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 + +## 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 From 9c2d02eae0897db32a6bc2cdbfc9e8c0221e7240 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:39:19 +0100 Subject: [PATCH 0138/1444] New translations network.md (Spanish) --- .../current/stacks-academy/network.md | 146 ++++++++++++++++++ 1 file changed, 146 insertions(+) create mode 100644 i18n/es/docusaurus-plugin-content-docs/current/stacks-academy/network.md diff --git a/i18n/es/docusaurus-plugin-content-docs/current/stacks-academy/network.md b/i18n/es/docusaurus-plugin-content-docs/current/stacks-academy/network.md new file mode 100644 index 0000000000..1e24195cb1 --- /dev/null +++ b/i18n/es/docusaurus-plugin-content-docs/current/stacks-academy/network.md @@ -0,0 +1,146 @@ +--- +title: Red +description: Guía de la red Stacks 2.0 +sidebar_position: 5 +--- + +## 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 To set the function call arguments and read the result, Clarity values need to be serialized into a hexadecimal string. 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 +} +``` From abaef823ba7ae4b6683042dde41860756babd1bb Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:39:19 +0100 Subject: [PATCH 0139/1444] New translations stacking.md (Spanish) --- .../current/stacks-academy/stacking.md | 151 ++++++++++++++++++ 1 file changed, 151 insertions(+) create mode 100644 i18n/es/docusaurus-plugin-content-docs/current/stacks-academy/stacking.md diff --git a/i18n/es/docusaurus-plugin-content-docs/current/stacks-academy/stacking.md b/i18n/es/docusaurus-plugin-content-docs/current/stacks-academy/stacking.md new file mode 100644 index 0000000000..8b931297fa --- /dev/null +++ b/i18n/es/docusaurus-plugin-content-docs/current/stacks-academy/stacking.md @@ -0,0 +1,151 @@ +--- +title: Stacking +description: Introducción al mecanismo de recompensa de la prueba de transferencia +sidebar_position: 11 +--- + +## Introducción + +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. 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. + +![](/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 Stacking functionality is implemented as a smart contract, using [Clarity](../clarity/). [Read more about the contract](../clarity/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 + +## 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 + +[Here](https://blog.stacks.co/stacking-strategy) is an interesting article that may help you choose the right Stacking strategy. + +## Where to Stack? + +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 + +Stacking on a pool allows Stacking without the requirement of the protocol minimum. + +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) From d564227a5d8b978a3f2c9439f5933902fe769eb3 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:39:20 +0100 Subject: [PATCH 0140/1444] New translations technical-specs.md (Spanish) --- .../current/stacks-academy/technical-specs.md | 79 +++++++++++++++++++ 1 file changed, 79 insertions(+) create mode 100644 i18n/es/docusaurus-plugin-content-docs/current/stacks-academy/technical-specs.md diff --git a/i18n/es/docusaurus-plugin-content-docs/current/stacks-academy/technical-specs.md b/i18n/es/docusaurus-plugin-content-docs/current/stacks-academy/technical-specs.md new file mode 100644 index 0000000000..a955bd3359 --- /dev/null +++ b/i18n/es/docusaurus-plugin-content-docs/current/stacks-academy/technical-specs.md @@ -0,0 +1,79 @@ +--- +title: Especificaciones técnicas +description: Resumen de las especificaciones técnicas de Stacks 2.0 +sidebar_position: 13 +--- + +## 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 whitepaper v2](https://www.youtube.com/watch?v=Wd-Bfe8Sn-Y). From 0325059871daa281856d3ab9d5b19a823a5e16e8 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:39:21 +0100 Subject: [PATCH 0141/1444] New translations testnet.md (Spanish) --- .../current/stacks-academy/testnet.md | 35 +++++++++++++++++++ 1 file changed, 35 insertions(+) create mode 100644 i18n/es/docusaurus-plugin-content-docs/current/stacks-academy/testnet.md diff --git a/i18n/es/docusaurus-plugin-content-docs/current/stacks-academy/testnet.md b/i18n/es/docusaurus-plugin-content-docs/current/stacks-academy/testnet.md new file mode 100644 index 0000000000..214b327dd8 --- /dev/null +++ b/i18n/es/docusaurus-plugin-content-docs/current/stacks-academy/testnet.md @@ -0,0 +1,35 @@ +--- +title: Testnet +description: Prueba tus contratos inteligentes y aplicaciones +sidebar_position: 12 +--- + +## Acerca de Testnet + +The testnet is a separate blockchain from the Stacks mainnet analogous to a staging environnement. 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. + +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) From 77aa7a91bc3ba7b7eb8ce040dc1bc1aeb1715d4d Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:39:22 +0100 Subject: [PATCH 0142/1444] New translations transactions.md (Spanish) --- .../current/stacks-academy/transactions.md | 40 +++++++++++++++++++ 1 file changed, 40 insertions(+) create mode 100644 i18n/es/docusaurus-plugin-content-docs/current/stacks-academy/transactions.md diff --git a/i18n/es/docusaurus-plugin-content-docs/current/stacks-academy/transactions.md b/i18n/es/docusaurus-plugin-content-docs/current/stacks-academy/transactions.md new file mode 100644 index 0000000000..5ebb5402b6 --- /dev/null +++ b/i18n/es/docusaurus-plugin-content-docs/current/stacks-academy/transactions.md @@ -0,0 +1,40 @@ +--- +title: Transacciones +description: Guía de transacciones Stacks 2.0 +sidebar_position: 9 +--- + +## 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). ::: From 27e4404d6c8fb9bc106e72e79b01d0ab747f207a Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:39:24 +0100 Subject: [PATCH 0143/1444] New translations language-functions.md (Spanish) --- .../current/clarity/language-functions.md | 2030 +++++++++++++++++ 1 file changed, 2030 insertions(+) create mode 100644 i18n/es/docusaurus-plugin-content-docs/current/clarity/language-functions.md diff --git a/i18n/es/docusaurus-plugin-content-docs/current/clarity/language-functions.md b/i18n/es/docusaurus-plugin-content-docs/current/clarity/language-functions.md new file mode 100644 index 0000000000..ff13c975c9 --- /dev/null +++ b/i18n/es/docusaurus-plugin-content-docs/current/clarity/language-functions.md @@ -0,0 +1,2030 @@ +--- +title: Funciones +description: Vea una lista detallada de todas las funciones del lenguaje Clarity. +sidebar_position: 3 +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` + +#### salida: `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` + +#### salida: `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` + +#### salida: `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: + +#### 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` + +#### salida: `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, ...` + +#### salida: `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` + +#### salida: `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` + +#### salida: `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` + +#### salida: `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` + +#### salida: `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)` + +#### salida: `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-existent\"))))) ;; Returns 0 +``` + +### asserts! + +#### input: `bool, C` + +#### salida: `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-existent\") ;; 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-existent\" })) ;; 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)` + +#### salida: `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)` + +#### salida: `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-existent\" }))) ;; Returns true +``` + +### is-err + +#### entrada: `(response A B)` + +#### salida: `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)` + +#### salida: `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-existent\" }))) ;; 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 \"Stacks\" '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 successfully 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_ transferred from another principal, but rather minted. + +If a non-positive amount is provided to mint, this function returns `(err 1)`. Otherwise, on successfully 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_ transferred 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 successfully 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 successfully 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)) +``` From c0884107e18265864137a0de1f0e5ed2fbe16c19 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:39:24 +0100 Subject: [PATCH 0144/1444] New translations language-keywords.md (Spanish) --- .../current/clarity/language-keywords.md | 146 ++++++++++++++++++ 1 file changed, 146 insertions(+) create mode 100644 i18n/es/docusaurus-plugin-content-docs/current/clarity/language-keywords.md diff --git a/i18n/es/docusaurus-plugin-content-docs/current/clarity/language-keywords.md b/i18n/es/docusaurus-plugin-content-docs/current/clarity/language-keywords.md new file mode 100644 index 0000000000..414f40a387 --- /dev/null +++ b/i18n/es/docusaurus-plugin-content-docs/current/clarity/language-keywords.md @@ -0,0 +1,146 @@ +--- +title: Palabras clave +description: Vea una lista detallada de todas las palabras clave para el lenguaje Clarity. +sidebar_position: 4 +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 + +#### salida: `bool` + +#### descripción: + +Boolean true constant. + +#### ejemplo: + +```clarity +(and true false) ;; Evaluates to false +(or false true) ;; Evaluates to true +``` + +### false + +#### salida: `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 + +#### salida: `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 +``` From 3d42d6c5d737f7cea6bfe5e80cc318383051737d Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:39:25 +0100 Subject: [PATCH 0145/1444] New translations language-types.md (Spanish) --- .../current/clarity/language-types.md | 25 +++++++++++++++++++ 1 file changed, 25 insertions(+) create mode 100644 i18n/es/docusaurus-plugin-content-docs/current/clarity/language-types.md diff --git a/i18n/es/docusaurus-plugin-content-docs/current/clarity/language-types.md b/i18n/es/docusaurus-plugin-content-docs/current/clarity/language-types.md new file mode 100644 index 0000000000..045d9a4289 --- /dev/null +++ b/i18n/es/docusaurus-plugin-content-docs/current/clarity/language-types.md @@ -0,0 +1,25 @@ +--- +title: Tipos +description: Vea una lista detallada de todos los tipos para el lenguaje Clarity. +sidebar_position: 2 +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. | From 1e551f023740e069f5e64e1a949b831a2d7816a1 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:39:27 +0100 Subject: [PATCH 0146/1444] New translations verify-miner.md (Spanish) --- .../current/nodes-and-miners/verify-miner.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) 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 index 094e3f03a1..18e8dd3a48 100644 --- 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 @@ -7,7 +7,7 @@ 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 +$ 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 -``` \ No newline at end of file +``` From d89ef4158911e8432d9e326da2ff98585632fe7e Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:39:28 +0100 Subject: [PATCH 0147/1444] New translations stacks-blockchain-api.md (Spanish) --- .../stacks-academy/stacks-blockchain-api.md | 41 +++++++++++++++++++ 1 file changed, 41 insertions(+) create mode 100644 i18n/es/docusaurus-plugin-content-docs/current/stacks-academy/stacks-blockchain-api.md diff --git a/i18n/es/docusaurus-plugin-content-docs/current/stacks-academy/stacks-blockchain-api.md b/i18n/es/docusaurus-plugin-content-docs/current/stacks-academy/stacks-blockchain-api.md new file mode 100644 index 0000000000..1da394f495 --- /dev/null +++ b/i18n/es/docusaurus-plugin-content-docs/current/stacks-academy/stacks-blockchain-api.md @@ -0,0 +1,41 @@ +--- +title: Stacks Blockchain API +description: Interacting with the Stacks 2.0 Blockchain via API +sidebar_position: 6 +--- + +## Introducción +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`. ::: From a2d04fd07b2b3293a0350280f5d5952cfee47b0a Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:39:29 +0100 Subject: [PATCH 0148/1444] New translations run-a-node.md (Spanish) --- .../current/nodes-and-miners/run-a-node.md | 329 +++--------------- 1 file changed, 42 insertions(+), 287 deletions(-) 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 index 94d938c5ca..7a7836f90e 100644 --- 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 @@ -1,5 +1,5 @@ --- -title: Run a node +title: Run a Node with Docker description: Set up and run a Stacks node sidebar_position: 1 tags: @@ -8,344 +8,99 @@ tags: ## Stacks Blockchain with Docker -Run your own Stacks Blockchain node easily with just few commands. +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) -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](./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) +- [Configuración](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) -## **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 -``` +## **Requirements:** -- With optional proxy: +The **minimum viable requirements** are listed below. -```bash -./manage.sh -n -a start -f proxy -``` +While you _can_ run a node using these specs, it's _recommended_ to assign more than the minimum for better performance. -- With optional bitcoin node: +- ⚠️ [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_ ) -```bash -./manage.sh -n -a start -f bitcoin -``` +:::caution MacOS with an ARM processor is NOT recommended -5. **Stop the Services** +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. ::: -```bash -./manage.sh -n -a stop -``` - -6. **Retrieve Service Logs** - -```bash -./manage.sh -n -a logs -``` - -- Export docker log files to `./exported-logs`: +## **Quickstart** -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. +The `` placeholder used below can be replaced with one of: -```bash -./manage.sh -n -a logs export -``` +- mainnet +- testnet +- mocknet -7. **Restart all services** +1. **Clone the stacks-blockchain-docker repository locally** ```bash -./manage.sh -n -a restart +git clone https://github.com/stacks-network/stacks-blockchain-docker && cd stacks-blockchain-docker ``` -- With optional proxy: +2. **Start the Services** ```bash -./manage.sh -n -a restart -f proxy +./manage.sh -n -a start ``` -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. +:::note With an optional HTTP proxy on port 80: ```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. - +./manage.sh -n -a start -f proxy ``` -9. **Download BNS data to** `./persistent-data/bns-data` - -```bash -./manage.sh bns -``` +::: -10. **Export stacks-blockchain-api events** (_Not applicable for mocknet_) +## **Accessing the services** -```bash -./manage.sh -n -a export -# check logs for completion -./manage.sh -n -a restart -``` +:::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. -11. **Replay stacks-blockchain-api events** (_Not applicable for mocknet_) +Follow the logs to track the sync progress: ```bash -./manage.sh -n -a import -# check logs for completion -./manage.sh -n -a restart +./manage.sh -n -a logs ``` -## **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` +- Ports `20443-20444` are exposed on `localhost` ```bash -curl -sL localhost:20443/v2/info | jq +curl -sL localhost:20443/v2/info | jq -r ``` **stacks-blockchain-api**: -- Port `3999` are exposed to `localhost` +- Port `3999` is exposed on `localhost` ```bash -curl -sL localhost:3999/v2/info | jq +curl -sL localhost:3999 | jq -r ``` **proxy**: -- Port `80` is exposed to `localhost` +- Port `80` is exposed on `localhost` ```bash -curl -sL localhost/v2/info | jq -curl -sL localhost/ | jq +curl -sL localhost/v2/info | jq -r +curl -sL localhost | jq -r ``` --- ## 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 -``` +:::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): ::: --- - -## **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 From 8868c888789e626d8aff8bdbbf5747c4ec4e0790 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:39:30 +0100 Subject: [PATCH 0149/1444] New translations index.md (Spanish) --- .../current/clarity/index.md | 58 +++++++++++++++++++ 1 file changed, 58 insertions(+) create mode 100644 i18n/es/docusaurus-plugin-content-docs/current/clarity/index.md diff --git a/i18n/es/docusaurus-plugin-content-docs/current/clarity/index.md b/i18n/es/docusaurus-plugin-content-docs/current/clarity/index.md new file mode 100644 index 0000000000..908a4bea3a --- /dev/null +++ b/i18n/es/docusaurus-plugin-content-docs/current/clarity/index.md @@ -0,0 +1,58 @@ +--- +title: Clarity Overview +description: Resumen y guías para comenzar con 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?2 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. If you are unsure what this means, let it not worry you for now. The serious advantage of decidability will become more apparent over time. + +### 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. From e67da2a4e2b9e9992c9d2c61669fc856c61238fb Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:39:30 +0100 Subject: [PATCH 0150/1444] New translations index.md (Spanish) --- .../current/stacks-academy/index.md | 11 +++++++++++ 1 file changed, 11 insertions(+) create mode 100644 i18n/es/docusaurus-plugin-content-docs/current/stacks-academy/index.md diff --git a/i18n/es/docusaurus-plugin-content-docs/current/stacks-academy/index.md b/i18n/es/docusaurus-plugin-content-docs/current/stacks-academy/index.md new file mode 100644 index 0000000000..a5bdb3c790 --- /dev/null +++ b/i18n/es/docusaurus-plugin-content-docs/current/stacks-academy/index.md @@ -0,0 +1,11 @@ +--- +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. From cd1e599c5ca4109ef057c5a3147c16256bb25156 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:39:31 +0100 Subject: [PATCH 0151/1444] New translations proof-of-transfer.md (Spanish) --- .../stacks-academy/proof-of-transfer.md | 83 +++++++++++++++++++ 1 file changed, 83 insertions(+) create mode 100644 i18n/es/docusaurus-plugin-content-docs/current/stacks-academy/proof-of-transfer.md diff --git a/i18n/es/docusaurus-plugin-content-docs/current/stacks-academy/proof-of-transfer.md b/i18n/es/docusaurus-plugin-content-docs/current/stacks-academy/proof-of-transfer.md new file mode 100644 index 0000000000..30d5c8a6df --- /dev/null +++ b/i18n/es/docusaurus-plugin-content-docs/current/stacks-academy/proof-of-transfer.md @@ -0,0 +1,83 @@ +--- +title: Prueba de transferencia +description: Conozca el mecanismo de consenso de prueba de transferencia +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. + +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. + +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. + +![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. Thus, PoX blockchains are anchored on their chosen PoW chain. 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. Lastly, Bitcoin is largely considered a reliable store of value, and provides extensive infrastructure to support the PoX consensus mechanism. + +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). + +:::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. +::: + +## 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 + +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. + +![Desbloquear 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. From 94bfa08e65183f33fe17c58c3fe7c0d6598729b1 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:39:32 +0100 Subject: [PATCH 0152/1444] New translations what-is-stacks.md (Spanish) --- .../current/stacks-academy/what-is-stacks.md | 102 ++++++++++++++++++ 1 file changed, 102 insertions(+) create mode 100644 i18n/es/docusaurus-plugin-content-docs/current/stacks-academy/what-is-stacks.md diff --git a/i18n/es/docusaurus-plugin-content-docs/current/stacks-academy/what-is-stacks.md b/i18n/es/docusaurus-plugin-content-docs/current/stacks-academy/what-is-stacks.md new file mode 100644 index 0000000000..94277da8a9 --- /dev/null +++ b/i18n/es/docusaurus-plugin-content-docs/current/stacks-academy/what-is-stacks.md @@ -0,0 +1,102 @@ +--- +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. + +There's a lot of jargon, possible assumptions, controversy, and cool technology wrapped up in those statements. So let's get started by getting a 30,000 foot view of what exactly Stacks is. + +## Stacks Explained in (Slightly Less Than) 10 Minutes + +
+ +
+ +## 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, Stacks takes a different approach. + +## 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). + +By taking this 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 with some unique properties, like having its own token, that allow it to maintain a historical ledger of all of its transactions and operate with its own security budget. + +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_. + +Nope. 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. From ac9b99937951d7f3fa0d05bcd7a8db98b9e8f72b Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:39:33 +0100 Subject: [PATCH 0153/1444] New translations community-tutorials.md (Spanish) --- .../current/tutorials/community-tutorials.md | 24 +++++++++++++++++++ 1 file changed, 24 insertions(+) create mode 100644 i18n/es/docusaurus-plugin-content-docs/current/tutorials/community-tutorials.md diff --git a/i18n/es/docusaurus-plugin-content-docs/current/tutorials/community-tutorials.md b/i18n/es/docusaurus-plugin-content-docs/current/tutorials/community-tutorials.md new file mode 100644 index 0000000000..a4f3d970ca --- /dev/null +++ b/i18n/es/docusaurus-plugin-content-docs/current/tutorials/community-tutorials.md @@ -0,0 +1,24 @@ +--- +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/) From 4f1d9339da1aa0961b1f9ad1fae4ffbb2a07db5b Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:39:34 +0100 Subject: [PATCH 0154/1444] New translations hello-stacks.md (Spanish) --- .../current/tutorials/hello-stacks.md | 759 ++++++++++++++++++ 1 file changed, 759 insertions(+) create mode 100644 i18n/es/docusaurus-plugin-content-docs/current/tutorials/hello-stacks.md diff --git a/i18n/es/docusaurus-plugin-content-docs/current/tutorials/hello-stacks.md b/i18n/es/docusaurus-plugin-content-docs/current/tutorials/hello-stacks.md new file mode 100644 index 0000000000..080f2b0cdd --- /dev/null +++ b/i18n/es/docusaurus-plugin-content-docs/current/tutorials/hello-stacks.md @@ -0,0 +1,759 @@ +--- +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/) + +### Universo de Clarity + +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. From ac3df6252498bd9b0a814c1f366fea94f25986b8 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:39:35 +0100 Subject: [PATCH 0155/1444] New translations index.md (Spanish) --- .../current/tutorials/index.md | 11 +++++++++++ 1 file changed, 11 insertions(+) create mode 100644 i18n/es/docusaurus-plugin-content-docs/current/tutorials/index.md diff --git a/i18n/es/docusaurus-plugin-content-docs/current/tutorials/index.md b/i18n/es/docusaurus-plugin-content-docs/current/tutorials/index.md new file mode 100644 index 0000000000..1d544c7bc1 --- /dev/null +++ b/i18n/es/docusaurus-plugin-content-docs/current/tutorials/index.md @@ -0,0 +1,11 @@ +--- +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. From 9586dcc831f6de51b756b0011cc69fb1d0e0d9cf Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:39:35 +0100 Subject: [PATCH 0156/1444] New translations satoshis-ridge.md (Spanish) --- .../current/tutorials/satoshis-ridge.md | 75 +++++++++++++++++++ 1 file changed, 75 insertions(+) create mode 100644 i18n/es/docusaurus-plugin-content-docs/current/tutorials/satoshis-ridge.md diff --git a/i18n/es/docusaurus-plugin-content-docs/current/tutorials/satoshis-ridge.md b/i18n/es/docusaurus-plugin-content-docs/current/tutorials/satoshis-ridge.md new file mode 100644 index 0000000000..ee7482804c --- /dev/null +++ b/i18n/es/docusaurus-plugin-content-docs/current/tutorials/satoshis-ridge.md @@ -0,0 +1,75 @@ +--- +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. + +## Pre requisitos + +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 arguable one of its strengths. + +Instead, we need to create separate layers that add additional functionality without modify 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. From de406e16946f907eeaf6ab5a5c2d1c20ceaea589 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:39:36 +0100 Subject: [PATCH 0157/1444] New translations crash-course.md (Spanish) --- .../current/clarity/crash-course.md | 122 ++++++++++++++++++ 1 file changed, 122 insertions(+) create mode 100644 i18n/es/docusaurus-plugin-content-docs/current/clarity/crash-course.md diff --git a/i18n/es/docusaurus-plugin-content-docs/current/clarity/crash-course.md b/i18n/es/docusaurus-plugin-content-docs/current/clarity/crash-course.md new file mode 100644 index 0000000000..5b27a3c275 --- /dev/null +++ b/i18n/es/docusaurus-plugin-content-docs/current/clarity/crash-course.md @@ -0,0 +1,122 @@ +--- +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.md). + +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. + +```clojure +(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: + +```clojure +(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. From 591e172c4e2f744bf5a4a49e5b46e476b1e086e6 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:39:37 +0100 Subject: [PATCH 0158/1444] New translations sample-contracts.md (Spanish) --- .../current/clarity/sample-contracts.md | 14 ++++++++++++++ 1 file changed, 14 insertions(+) create mode 100644 i18n/es/docusaurus-plugin-content-docs/current/clarity/sample-contracts.md diff --git a/i18n/es/docusaurus-plugin-content-docs/current/clarity/sample-contracts.md b/i18n/es/docusaurus-plugin-content-docs/current/clarity/sample-contracts.md new file mode 100644 index 0000000000..adb12a58fd --- /dev/null +++ b/i18n/es/docusaurus-plugin-content-docs/current/clarity/sample-contracts.md @@ -0,0 +1,14 @@ +--- +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) From 0a3d608806526c66013d976b14bb76814e39074c Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:39:38 +0100 Subject: [PATCH 0159/1444] New translations index.md (Spanish) --- .../current/cookbook/index.md | 64 +++++++++++++++++++ 1 file changed, 64 insertions(+) create mode 100644 i18n/es/docusaurus-plugin-content-docs/current/cookbook/index.md diff --git a/i18n/es/docusaurus-plugin-content-docs/current/cookbook/index.md b/i18n/es/docusaurus-plugin-content-docs/current/cookbook/index.md new file mode 100644 index 0000000000..a2b0e42eea --- /dev/null +++ b/i18n/es/docusaurus-plugin-content-docs/current/cookbook/index.md @@ -0,0 +1,64 @@ +--- +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 + +Swapping between Bitcoin and Stacks addresses + +Swapping between xBTC and BTC + +Verifying a transaction on the BTC chain + +## 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 + +Airdropping an NFT to a Bitcoin address + +## Stacking and Mining + +Simple stacking pool + +Continuous stacking + +Simple mining pool + +Proof of PoX payout + +## Oracles + +Creating a simple BTC price oracle + +## Frontend + +[Post conditions with Stacks.js](./post-conditions) + +[Authentication with Stacks.js](./stacks-js-auth) + +[Sending transactions with Stacks.js](./stacks-js-sending-transactions) + +## Complete Apps + +[Sup](https://github.com/kenrogers/sup) + +[Hello Stacks](https://github.com/kenrogers/hello-stacks) From cb70b3d0025de62741f625c2d3bfb1e66c1d8e33 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:39:39 +0100 Subject: [PATCH 0160/1444] New translations btc-connection.md (Spanish) --- .../current/stacks-academy/btc-connection.md | 196 ++++++++++++++++++ 1 file changed, 196 insertions(+) create mode 100644 i18n/es/docusaurus-plugin-content-docs/current/stacks-academy/btc-connection.md diff --git a/i18n/es/docusaurus-plugin-content-docs/current/stacks-academy/btc-connection.md b/i18n/es/docusaurus-plugin-content-docs/current/stacks-academy/btc-connection.md new file mode 100644 index 0000000000..b4db915969 --- /dev/null +++ b/i18n/es/docusaurus-plugin-content-docs/current/stacks-academy/btc-connection.md @@ -0,0 +1,196 @@ +--- +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. + +## Stacks Among Other Bitcoin Layers + +In the [last section](./what-is-stacks.md) we covered what Stacks actually is and what problem it is solving, but this is not a new problem. The Bitcoin write problem has been a bit of a holy grail problem in the crypto world for a while now. + +Bitcoin is the OG cryptocurrency and has the largest market cap, but it also some of the least functionality, which means if we want to make it a productive asset and use it to build a decentralized economy, we need to take a layered approach and let Bitcoin do what it does best, while creating additional layers on top of it to add functionality. + +So how does Stacks compare to some of the other approaches to layering on top of Bitcoin? + +### 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. + +## 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. + +But because it has its own execution environment and smart contract state to maintain, it needs a token to incentivize maintenance of the network. + +But it goes further than that. It is possible to build a system like this without a token using something like merge-mining or a sidechain, but then we lose out on the additional benefit of having the chain state's safety underpinned by its entire token economy's value. + +In the case of Stacks, the safety and liveness of the chain are underpinned by this value, and the stacking mechanism incentivizes network members to increase this value. + +From Jude Nelson, Stacks core developer: + +"How hard is it to cause a safety failure (i.e. a double-spend via a reorg) on just the canonical Stacks chain fork? Anyone can become a miner by spending BTC, so without loss of generality, reverting the last block on the canonical chain is at least as hard in expectation as spending more BTC than the rest of the miners combined for that block. Because each Bitcoin block selects at most one Stacks block, the act of reorging the canonical Stacks chain back N blocks is the act of winning at least N + 1 blocks built off of a common ancestor that is N blocks deep. This is a lower bound on the number of Bitcoin blocks mined during which a reorg needs to take place — in practice, honest miners will keep working on the canonical chain, and will win some Stacks blocks of their own, which in turn increases the number of Stacks blocks the reorging miners must win. + +How costly is it to carry out a reorg of N blocks? It’s a function of how valuable STX is relative to BTC — the more valuable STX are, the more BTC honest miners are committing to mining (this has borne out in practice), and thus the more BTC a reorging miner must commit. Therefore, the cost of a reorg is a function of the value of STX. + +This is similar to the economic security of a PoW blockchain. Like in PoW, each fork of the Stacks chain has its own independent “security budget” — an attacker must out-spend the security budget to carry out a reorg, and the security budget is a function of the block rewards. In PoX, the only difference is that the miners spend another blockchain’s tokens (BTC in Stacks’ case) instead of energy. Therefore, Stacks can’t be a sidechain, a drivechain, or a merge-mined chain, because none of these other systems’ security budgets are a function of their tokens’ worth. Sidechains, drivechains, and merged-mined chains all rely on external miners for their safety, since their safety is guaranteed in part by external miners validating their blocks. The onus on these systems is to get external miners to care enough to do so, and in the case of sidechains, drivechains, and blind merged-mined chains, there is an additional onus to encourage their nodes to mine blocks at all (since there is no on-chain reward for them to earn by doing so). By contrast, disinterested Bitcoin miners neither assist nor prevent a reorg in PoX — they only record the history of all Stacks forks. + +PoX offers two additional, unique security properties on top of PoW. First, no matter how much BTC a reorging miner can commit, the act of executing a reorg is going to be time-consuming. Unless the attacker can attack the Bitcoin chain itself by quickly producing a better Bitcoin fork, a reorging miner must sustain the attack for at least N + 1 Bitcoin blocks. This gives honest miners and users ample time to notice and react to the reorg attempt. + +Second, the history of block production in all Stacks forks is embedded within Bitcoin. This allows the system to leverage Bitcoin’s security budget in order to ensure that all forks are public. This is because the act of producing a hidden Stacks fork, where the fork’s block hashes are not known to the honest miners, is the act of producing a hidden canonical Bitcoin fork. Therefore, the act of producing a hidden Stacks fork is at least as hard as reorging the Bitcoin chain. A PoX chain leverages this property not to prevent reorgs, but to make reorgs unprofitable. + +By anchoring blocks to an existing blockchain, a PoX chain forces reorgs to happen out in the open, thereby giving advance warning to all honest network participants when they happen. Honest miners, users, and exchanges will see the PoX transactions for reorg attempts on the existing blockchain, and adapt their behaviors accordingly: honest miners will increase their commitments, and users and exchanges will require more confirmations for transactions. This makes the act of carrying out a reorg while also making a profit much more challenging, since malicious reorgs — like selfish mining and double-spending — rely on secrecy to work effectively. Specific to Stacks, miners are additionally required to mine for a “warm-up” period of two blocks, during which they must spend BTC at their target commit levels but will not win any Stacks blocks. So, a high-budget reorg attempt will not only be costly, but will also alert the rest of the network before the damage is done." + +- [What Kind of Blockchain is Stacks?](https://stacks.org/stacks-blockchain) + +## 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) From 3533b2ca8cb59d06127a20e87ec678fcb43e8313 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:39:40 +0100 Subject: [PATCH 0161/1444] New translations post-conditions.md (Spanish) --- .../current/stacks-academy/post-conditions.md | 39 +++++++++++++++++++ 1 file changed, 39 insertions(+) create mode 100644 i18n/es/docusaurus-plugin-content-docs/current/stacks-academy/post-conditions.md diff --git a/i18n/es/docusaurus-plugin-content-docs/current/stacks-academy/post-conditions.md b/i18n/es/docusaurus-plugin-content-docs/current/stacks-academy/post-conditions.md new file mode 100644 index 0000000000..bb0727194f --- /dev/null +++ b/i18n/es/docusaurus-plugin-content-docs/current/stacks-academy/post-conditions.md @@ -0,0 +1,39 @@ +--- +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). From 389a6e0657e7edae8883553fef561de49e881190 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:39:41 +0100 Subject: [PATCH 0162/1444] New translations creating-an-ft.md (Spanish) --- .../current/cookbook/creating-an-ft.md | 99 +++++++++++++++++++ 1 file changed, 99 insertions(+) create mode 100644 i18n/es/docusaurus-plugin-content-docs/current/cookbook/creating-an-ft.md diff --git a/i18n/es/docusaurus-plugin-content-docs/current/cookbook/creating-an-ft.md b/i18n/es/docusaurus-plugin-content-docs/current/cookbook/creating-an-ft.md new file mode 100644 index 0000000000..4e3bad99d2 --- /dev/null +++ b/i18n/es/docusaurus-plugin-content-docs/current/cookbook/creating-an-ft.md @@ -0,0 +1,99 @@ +--- +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) + ) +) +``` From b00bc71fbffb2161d1f8db6c7336d5f7d15e6818 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:39:42 +0100 Subject: [PATCH 0163/1444] New translations creating-an-nft.md (Spanish) --- .../current/cookbook/creating-an-nft.md | 87 +++++++++++++++++++ 1 file changed, 87 insertions(+) create mode 100644 i18n/es/docusaurus-plugin-content-docs/current/cookbook/creating-an-nft.md diff --git a/i18n/es/docusaurus-plugin-content-docs/current/cookbook/creating-an-nft.md b/i18n/es/docusaurus-plugin-content-docs/current/cookbook/creating-an-nft.md new file mode 100644 index 0000000000..08faf9393a --- /dev/null +++ b/i18n/es/docusaurus-plugin-content-docs/current/cookbook/creating-an-nft.md @@ -0,0 +1,87 @@ +--- +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 +Code for this recipe has been pulled from [this NFT tutorial](https://blog.developerdao.com/building-an-nft-with-stacks-and-clarity) from Developer DAO. +::: + +## 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) + ) +) +``` From 9fe63b92d4701e85e15a02eb0926342054793215 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:39:42 +0100 Subject: [PATCH 0164/1444] New translations post-conditions.md (Spanish) --- .../current/cookbook/post-conditions.md | 136 ++++++++++++++++++ 1 file changed, 136 insertions(+) create mode 100644 i18n/es/docusaurus-plugin-content-docs/current/cookbook/post-conditions.md diff --git a/i18n/es/docusaurus-plugin-content-docs/current/cookbook/post-conditions.md b/i18n/es/docusaurus-plugin-content-docs/current/cookbook/post-conditions.md new file mode 100644 index 0000000000..571fc20d48 --- /dev/null +++ b/i18n/es/docusaurus-plugin-content-docs/current/cookbook/post-conditions.md @@ -0,0 +1,136 @@ +--- +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. From c5cf652c3a3906f3abee021b57ff1817d50a06ae Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:39:43 +0100 Subject: [PATCH 0165/1444] New translations stacks-js-auth.md (Spanish) --- .../current/cookbook/stacks-js-auth.md | 98 +++++++++++++++++++ 1 file changed, 98 insertions(+) create mode 100644 i18n/es/docusaurus-plugin-content-docs/current/cookbook/stacks-js-auth.md diff --git a/i18n/es/docusaurus-plugin-content-docs/current/cookbook/stacks-js-auth.md b/i18n/es/docusaurus-plugin-content-docs/current/cookbook/stacks-js-auth.md new file mode 100644 index 0000000000..89d1f06e00 --- /dev/null +++ b/i18n/es/docusaurus-plugin-content-docs/current/cookbook/stacks-js-auth.md @@ -0,0 +1,98 @@ +--- +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 && ( + + ); +} +``` From f01a9c9aaf8f0fd664929bdca481f4b8f0c69d5c Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:39:44 +0100 Subject: [PATCH 0166/1444] New translations stacks-js-sending-transactions.md (Spanish) --- .../stacks-js-sending-transactions.md | 55 +++++++++++++++++++ 1 file changed, 55 insertions(+) create mode 100644 i18n/es/docusaurus-plugin-content-docs/current/cookbook/stacks-js-sending-transactions.md diff --git a/i18n/es/docusaurus-plugin-content-docs/current/cookbook/stacks-js-sending-transactions.md b/i18n/es/docusaurus-plugin-content-docs/current/cookbook/stacks-js-sending-transactions.md new file mode 100644 index 0000000000..849c7d1f42 --- /dev/null +++ b/i18n/es/docusaurus-plugin-content-docs/current/cookbook/stacks-js-sending-transactions.md @@ -0,0 +1,55 @@ +--- +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. From 3edb875efa80094c43a3025894f608149b0f7ccc Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:39:45 +0100 Subject: [PATCH 0167/1444] New translations _category_.json (Spanish) --- .../current/clarity/noteworthy-contracts/_category_.json | 8 ++++++++ 1 file changed, 8 insertions(+) create mode 100644 i18n/es/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/_category_.json diff --git a/i18n/es/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/_category_.json b/i18n/es/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/_category_.json new file mode 100644 index 0000000000..f5de305558 --- /dev/null +++ b/i18n/es/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/_category_.json @@ -0,0 +1,8 @@ +{ + "label": "Noteworthy Contracts", + "position": 4, + "link": { + "type": "generated-index", + "description": "Specific deployed Clarity Contracts worth mentioning." + } +} \ No newline at end of file From 9863560ec41d8e4dda748c13b92d80659756e9a2 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:39:46 +0100 Subject: [PATCH 0168/1444] New translations bns-contract.md (Spanish) --- .../noteworthy-contracts/bns-contract.md | 519 ++++++++++++++++++ 1 file changed, 519 insertions(+) create mode 100644 i18n/es/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/bns-contract.md diff --git a/i18n/es/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/bns-contract.md b/i18n/es/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/bns-contract.md new file mode 100644 index 0000000000..e7657922ca --- /dev/null +++ b/i18n/es/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/bns-contract.md @@ -0,0 +1,519 @@ +--- +title: BNS Contract +description: The Blockchain Naming System. +--- + +![](/img/satoshi-btc.png) + +## Introducción + +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 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` From 7e7fab28f722dc8c73fd8df1786864db6b3ffbc1 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:39:47 +0100 Subject: [PATCH 0169/1444] New translations xbtc.md (Spanish) --- .../clarity/noteworthy-contracts/xbtc.md | 28 +++++++++++++++++++ 1 file changed, 28 insertions(+) create mode 100644 i18n/es/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/xbtc.md diff --git a/i18n/es/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/xbtc.md b/i18n/es/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/xbtc.md new file mode 100644 index 0000000000..da5d9732a6 --- /dev/null +++ b/i18n/es/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/xbtc.md @@ -0,0 +1,28 @@ +--- +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/) 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) From c6bf1f58c54a6be48d23343c0f4e2415d7204286 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:39:48 +0100 Subject: [PATCH 0170/1444] New translations index.md (Spanish) --- .../current/glossary/index.md | 284 ++++++++++++++++++ 1 file changed, 284 insertions(+) create mode 100644 i18n/es/docusaurus-plugin-content-docs/current/glossary/index.md diff --git a/i18n/es/docusaurus-plugin-content-docs/current/glossary/index.md b/i18n/es/docusaurus-plugin-content-docs/current/glossary/index.md new file mode 100644 index 0000000000..419c0e0d73 --- /dev/null +++ b/i18n/es/docusaurus-plugin-content-docs/current/glossary/index.md @@ -0,0 +1,284 @@ +--- +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. From 217541100ee073082cee00eb3e1be27a1c0df7c7 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:39:49 +0100 Subject: [PATCH 0171/1444] New translations quicknode.md (Spanish) --- .../current/nodes-and-miners/quicknode.md | 45 +++++++++++++++++++ 1 file changed, 45 insertions(+) create mode 100644 i18n/es/docusaurus-plugin-content-docs/current/nodes-and-miners/quicknode.md diff --git a/i18n/es/docusaurus-plugin-content-docs/current/nodes-and-miners/quicknode.md b/i18n/es/docusaurus-plugin-content-docs/current/nodes-and-miners/quicknode.md new file mode 100644 index 0000000000..1281964689 --- /dev/null +++ b/i18n/es/docusaurus-plugin-content-docs/current/nodes-and-miners/quicknode.md @@ -0,0 +1,45 @@ +--- +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. From 81edf19725e8edc14e85767136641faf836120b7 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:39:50 +0100 Subject: [PATCH 0172/1444] New translations defi.md (Spanish) --- .../current/services-using-stacks/defi.md | 11 +++++------ 1 file changed, 5 insertions(+), 6 deletions(-) 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 index c4a1864f64..58717a3234 100644 --- 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 @@ -1,13 +1,13 @@ --- title: DeFi -description: Sitios De-Fi en Stacks +description: De-Fi sites on 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. +:::tip Are we missing one? +Please edit this page to add any relevant new site that we are missing. ::: ## Alex @@ -20,13 +20,13 @@ Por favor edita esta página para agregar cualquier sitio web relevante que falt ## Catamaran Swaps -[Catamaran Swaps](https://www.catamaranswaps.org/) permite el intercambio de activos digitales sin requirimiento de confianza. +[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 +[LNSWAP](https://www.lnswap.org). Non-custodial crypto currency exchange ![](/img/sh_lnswap.png) @@ -41,4 +41,3 @@ Por favor edita esta página para agregar cualquier sitio web relevante que falt [Stackswap](https://app.stackswap.org/v2) ![](/img/sh_stackswap.png) - From f50ff52e05896a332663d603b4daa82c4a3bce92 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:39:50 +0100 Subject: [PATCH 0173/1444] New translations more.md (Spanish) --- .../current/services-using-stacks/more.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) 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 index e28ff4727e..1e14b9a5a5 100644 --- 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 @@ -1,13 +1,13 @@ --- -title: Más -description: Más servicios construidos en Stacks. +title: More +description: More services built on Stacks. sidebar_position: 5 --- -Lista de sitios añadidos por la comunidad en orden alfabético. +List of sites on alphabetical order added by the community. -:::tip ¿Falta uno? -Por favor edita esta página para agregar cualquier sitio web relevante que falte. +:::tip Are we missing one? +Please edit this page to add any relevant new site that we are missing. ::: ## Citycoins @@ -18,6 +18,6 @@ Por favor edita esta página para agregar cualquier sitio web relevante que falt ## Sigle -[Sigle](https://www.sigle.io/) es una plataforma de escritura web 3 descentralizada y de código abierto. +[Sigle](https://www.sigle.io/) is a decentralized and open source web 3 writing platform. -![](/img/sh_sigle.png) \ No newline at end of file +![](/img/sh_sigle.png) From 6fe5432a592a5acbe2092bf91bfc336686f0ccbe Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:39:51 +0100 Subject: [PATCH 0174/1444] New translations nft.md (Spanish) --- .../current/services-using-stacks/nft.md | 19 ++++++++++--------- 1 file changed, 10 insertions(+), 9 deletions(-) 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 index 5851befe48..d582604854 100644 --- 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 @@ -1,29 +1,30 @@ --- title: NFTs -description: NFTs en Stacks +description: NFTs on Stacks sidebar_position: 3 --- -Lista de sitios web que operan NFTS en Stacks en orden alfabético. +List of sites that operate NFTS on Stacks on alphabetical order. -:::tip ¿Falta uno? -Por favor edita esta página para agregar cualquier sitio web relevante que falte. +:::tip Are we missing one? +Please edit this page to add any relevant new site that we are missing. ::: ### [Byzantion](https://byzantion.xyz/) -![captura de pantalla de página web](/img/sh_nft_byzantion.png) +![website-screenshot](/img/sh_nft_byzantion.png) ### [Gamma](https://gamma.io/) -![captura de pantalla de página web](/img/sh_nft_gamma.png) + +![website-screenshot](/img/sh_nft_gamma.png) ### [Megapont](https://www.megapont.com/) -![captura de pantalla de página web](/img/sh_nft_megapont.png) +![website-screenshot](/img/sh_nft_megapont.png) ### [Satoshibles](https://satoshibles.com/) -![captura de pantalla de página web](/img/sh_nft_satoshibles.png) +![website-screenshot](/img/sh_nft_satoshibles.png) ### [StacksArt](https://www.stacksart.com/) @@ -35,4 +36,4 @@ Por favor edita esta página para agregar cualquier sitio web relevante que falt ### [Superfandom](https://superfandom.io/) -![website-screenshot](/img/sh_superfandom.png) \ No newline at end of file +![website-screenshot](/img/sh_superfandom.png) From e3d30fe5a349972cec53a6486495a7a2ff69a501 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:39:52 +0100 Subject: [PATCH 0175/1444] New translations stacks-info-sites.md (Spanish) --- .../current/services-using-stacks/stacks-info-sites.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) 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 index 180d2da19d..54f6823e33 100644 --- 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 @@ -1,13 +1,13 @@ --- -title: Sitios web con información Stacks +title: Stacks info sites 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. +A list of sites on alphabetical order that display status and stats of the Stacks network. -:::tip ¿Falta uno? -Por favor edita esta página para agregar cualquier sitio web relevante que falte. +:::tip Are we missing one? +Please edit this page to add any relevant new site that we are missing. ::: ### [Haystack](https://haystack.tools/mempool) @@ -30,7 +30,7 @@ Por favor edita esta página para agregar cualquier sitio web relevante que falt ![website-screenshot](/img/sh_stxstats.png) -### [Novuminsights](https://stacks.novuminsights.com/health) +### [Novum Insights](https://stacks.novuminsights.com/health) ![website-screenshot](/img/sh_novuminsights.png) From 270108495d666fc84b6eb1be0f1652f69bf70138 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:39:53 +0100 Subject: [PATCH 0176/1444] New translations wallets.md (Spanish) --- .../current/services-using-stacks/wallets.md | 14 ++++++++------ 1 file changed, 8 insertions(+), 6 deletions(-) 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 index 9e9b57ec76..5fbeeecbff 100644 --- 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 @@ -1,13 +1,13 @@ --- -title: Wallets -description: Wallets para Stacks +title: Billeteras +description: Wallets for Stacks sidebar_position: 4 --- -Un listado de wallets de hardware y software para Stacks +A list of hardware and software wallets for Stacks -:::tip ¿Falta uno? -Por favor edita esta página para agregar cualquier sitio web relevante que falte. +:::tip Are we missing one? +Please edit this page to add any relevant new site that we are missing. ::: ## Blockchain.com @@ -15,6 +15,7 @@ Por favor edita esta página para agregar cualquier sitio web relevante que falt [Blockchain.com](https://www.blockchain.com/wallet) ![](/img/sh_blockchain.png) + ## Boom [Boom](https://boom.money) @@ -26,6 +27,7 @@ Por favor edita esta página para agregar cualquier sitio web relevante que falt [D'CENT](https://dcentwallet.com) ![](/img/sh_dcent.png) + ## Hiro Wallet [Hiro Wallet](https://www.hiro.so/wallet) @@ -48,4 +50,4 @@ Por favor edita esta página para agregar cualquier sitio web relevante que falt [Wise](https://wiseapp.id) -![](/img/sh_wiseapp.png) \ No newline at end of file +![](/img/sh_wiseapp.png) From 095c4d900bac4c6ab3963ae0070a808f8b1e68ee Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:39:54 +0100 Subject: [PATCH 0177/1444] New translations whitepapers.md (Spanish) --- .../current/stacks-academy/whitepapers.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) create mode 100644 i18n/es/docusaurus-plugin-content-docs/current/stacks-academy/whitepapers.md diff --git a/i18n/es/docusaurus-plugin-content-docs/current/stacks-academy/whitepapers.md b/i18n/es/docusaurus-plugin-content-docs/current/stacks-academy/whitepapers.md new file mode 100644 index 0000000000..2b5d805070 --- /dev/null +++ b/i18n/es/docusaurus-plugin-content-docs/current/stacks-academy/whitepapers.md @@ -0,0 +1,12 @@ +--- +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) +- [Prueba de transferencia](https://assets.website-files.com/5fcf9ac604d37418aa70a5ab/60072dbb32d416d6b3806935_5f1596b12bcc0800f3dcadcd_pox.pdf) +- [sBTC](https://assets.stacks.co/sbtc.pdf) From 75dd0b15c2344f760acd0b652ba90a533d0444f7 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:39:55 +0100 Subject: [PATCH 0178/1444] New translations stacking-contract.md (Spanish) --- .../noteworthy-contracts/stacking-contract.md | 352 ++++++++++++++++++ 1 file changed, 352 insertions(+) create mode 100644 i18n/es/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/stacking-contract.md diff --git a/i18n/es/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/stacking-contract.md b/i18n/es/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/stacking-contract.md new file mode 100644 index 0000000000..0ee88e2224 --- /dev/null +++ b/i18n/es/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/stacking-contract.md @@ -0,0 +1,352 @@ +--- +title: Stacking Contract +description: See a detailed list of all functions and error codes of the Stacking contract. +sidebar_position: 6 +--- + +## Introducción + +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)` + +#### 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 + +#### input: + +#### 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 + +#### input: + +#### 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. + +## 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)` + +#### descripción: + +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)` + +#### 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 + +#### input: + +#### 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 + +#### entrada: `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 + +#### entrada: `uint` + +#### salida: `bool` + +#### signature: `(is-pox-active reward-cycle)` + +#### descripción: + +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` From 7528ea986e9397e5da1f18371f56f6af9b1f74c4 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:39:56 +0100 Subject: [PATCH 0179/1444] New translations index.md (Spanish) --- .../current/next-steps/index.md | 39 +++++++++++++++++++ 1 file changed, 39 insertions(+) create mode 100644 i18n/es/docusaurus-plugin-content-docs/current/next-steps/index.md diff --git a/i18n/es/docusaurus-plugin-content-docs/current/next-steps/index.md b/i18n/es/docusaurus-plugin-content-docs/current/next-steps/index.md new file mode 100644 index 0000000000..00ddec9178 --- /dev/null +++ b/i18n/es/docusaurus-plugin-content-docs/current/next-steps/index.md @@ -0,0 +1,39 @@ +--- +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) From 0030e13faaf1a3b0b7486530118711f12eb34a22 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:39:57 +0100 Subject: [PATCH 0180/1444] New translations sips.md (Spanish) --- .../current/stacks-academy/sips.md | 52 +++++++++++++++++++ 1 file changed, 52 insertions(+) create mode 100644 i18n/es/docusaurus-plugin-content-docs/current/stacks-academy/sips.md diff --git a/i18n/es/docusaurus-plugin-content-docs/current/stacks-academy/sips.md b/i18n/es/docusaurus-plugin-content-docs/current/stacks-academy/sips.md new file mode 100644 index 0000000000..aa2db18e62 --- /dev/null +++ b/i18n/es/docusaurus-plugin-content-docs/current/stacks-academy/sips.md @@ -0,0 +1,52 @@ +--- +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/IJ15791776) 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-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. From 4a995146149d6d75c3fa1983091483783746ef5f Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:39:58 +0100 Subject: [PATCH 0181/1444] New translations hosted-nodes.md (Spanish) --- .../current/nodes-and-miners/hosted-nodes.md | 25 +++++++++++++++++++ 1 file changed, 25 insertions(+) create mode 100644 i18n/es/docusaurus-plugin-content-docs/current/nodes-and-miners/hosted-nodes.md diff --git a/i18n/es/docusaurus-plugin-content-docs/current/nodes-and-miners/hosted-nodes.md b/i18n/es/docusaurus-plugin-content-docs/current/nodes-and-miners/hosted-nodes.md new file mode 100644 index 0000000000..12d86c7ee2 --- /dev/null +++ b/i18n/es/docusaurus-plugin-content-docs/current/nodes-and-miners/hosted-nodes.md @@ -0,0 +1,25 @@ +--- +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. From e0a090b0533e95804301a44f746d6144831e842d Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:39:58 +0100 Subject: [PATCH 0182/1444] New translations authentication.md (German) --- .../current/stacks-academy/authentication.md | 63 +++++++++++++++++++ 1 file changed, 63 insertions(+) create mode 100644 i18n/de/docusaurus-plugin-content-docs/current/stacks-academy/authentication.md diff --git a/i18n/de/docusaurus-plugin-content-docs/current/stacks-academy/authentication.md b/i18n/de/docusaurus-plugin-content-docs/current/stacks-academy/authentication.md new file mode 100644 index 0000000000..10ac692bb9 --- /dev/null +++ b/i18n/de/docusaurus-plugin-content-docs/current/stacks-academy/authentication.md @@ -0,0 +1,63 @@ +--- +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/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. From 8f0c47eaab150244897ac60ae17167d63954cbbb Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:39:59 +0100 Subject: [PATCH 0183/1444] New translations bns.md (German) --- .../current/stacks-academy/bns.md | 242 ++++++++++++++++++ 1 file changed, 242 insertions(+) create mode 100644 i18n/de/docusaurus-plugin-content-docs/current/stacks-academy/bns.md diff --git a/i18n/de/docusaurus-plugin-content-docs/current/stacks-academy/bns.md b/i18n/de/docusaurus-plugin-content-docs/current/stacks-academy/bns.md new file mode 100644 index 0000000000..4c89d9e56c --- /dev/null +++ b/i18n/de/docusaurus-plugin-content-docs/current/stacks-academy/bns.md @@ -0,0 +1,242 @@ +--- +title: Blockchain Naming System +description: Binds Stacks usernames to off-chain state +sidebar_position: 8 +--- + +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 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). From 572002fc1c7ce0371e32462cfc74970a9a9e30fc Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:40:00 +0100 Subject: [PATCH 0184/1444] New translations docs.md (German) --- .../current/contribute/docs.md | 24 ++++++++++++------- 1 file changed, 15 insertions(+), 9 deletions(-) diff --git a/i18n/de/docusaurus-plugin-content-docs/current/contribute/docs.md b/i18n/de/docusaurus-plugin-content-docs/current/contribute/docs.md index 77705451b8..b2fef628f9 100644 --- a/i18n/de/docusaurus-plugin-content-docs/current/contribute/docs.md +++ b/i18n/de/docusaurus-plugin-content-docs/current/contribute/docs.md @@ -7,7 +7,7 @@ description: Learn how this site is built, and how you can contribute to it. 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). +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/). @@ -15,7 +15,7 @@ Don't want to learn it? No need to. Write [in plain text an issue on Github](htt :::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 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). @@ -24,28 +24,32 @@ To add new content, they are two different ways to do it, the [easy way](#easy-w [**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. +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 yourhanges in real time. + - `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. -## Aditional information +## 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 ``` @@ -54,8 +58,8 @@ Before running this command for the first time you will need to run `npm install 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 ``` @@ -91,7 +95,7 @@ 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. +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 @@ -124,6 +128,7 @@ And execute prettier with the following command: npx prettier --write mynewfiletocheck.md ``` --> + ### 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. @@ -138,6 +143,7 @@ To write a code block, you need to wrap your code in ` ```language `, and end yo (define-public (get-counter) (ok (var-get counter))) ``` + ### Admonitions You can use the following admonitions to highlight content. @@ -204,4 +210,4 @@ Some **content** with _markdown_ `syntax`. Some **content** with _markdown_ `syntax`. -::: \ No newline at end of file +::: From d943ad54caff3fc73115ba9cfa6fa879b3e3c3c9 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:40:02 +0100 Subject: [PATCH 0185/1444] New translations translations.md (German) --- .../current/contribute/translations.md | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/i18n/de/docusaurus-plugin-content-docs/current/contribute/translations.md b/i18n/de/docusaurus-plugin-content-docs/current/contribute/translations.md index bd9a452333..fe8f8c6027 100644 --- a/i18n/de/docusaurus-plugin-content-docs/current/contribute/translations.md +++ b/i18n/de/docusaurus-plugin-content-docs/current/contribute/translations.md @@ -1,25 +1,24 @@ --- title: Contribute with translations -description: Want to help tranlating these docs to your local language? +description: Want to help translating 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. +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 Crodin intead. +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 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 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) From 51f1d09006e607ad0924e11c6550482993db65bc Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:40:05 +0100 Subject: [PATCH 0186/1444] New translations gaia-on-ec2.md (German) --- .../current/gaia/gaia-on-ec2.md | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) 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 index 2067e7d57c..3f58ca5e68 100644 --- 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 @@ -26,9 +26,10 @@ Use a link in the table to launch the [CloudFormation](https://console.aws.amazo ### Step 2 - Setup stack using template -You need to configure the template with the appropiate values for your hub and domain it runs on. +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 ``` @@ -52,7 +53,7 @@ Specify the stack details and then click `Next`: ![Specify template](/img/cloudf | 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`. | +| 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 | @@ -93,7 +94,9 @@ ssh -i admin@ 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 +![](/img/cloudformation-gaia-template1-designer.png) From d0007856836e8a80a07688eee6899578c1c513f7 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:40:06 +0100 Subject: [PATCH 0187/1444] New translations gaia.md (German) --- .../current/gaia/gaia.md | 12 +++++++++--- 1 file changed, 9 insertions(+), 3 deletions(-) diff --git a/i18n/de/docusaurus-plugin-content-docs/current/gaia/gaia.md b/i18n/de/docusaurus-plugin-content-docs/current/gaia/gaia.md index 1070857350..f86a0d61dc 100644 --- a/i18n/de/docusaurus-plugin-content-docs/current/gaia/gaia.md +++ b/i18n/de/docusaurus-plugin-content-docs/current/gaia/gaia.md @@ -1,14 +1,20 @@ --- title: Gaia description: Decentralized storage architecture for off-chain data -sidebar_position: 5 +sidebar_position: 6 tags: - gaia --- ## Introduction -Apps built with the Stacks blockchain store off-chain data using a storage system called Gaia. +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. @@ -38,7 +44,7 @@ The Stacks blockchain stores only identity data. Data created by the actions of 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) +![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. From 25ee4b659e7e6e36cac4da7545e5b5c778861d9a Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:40:07 +0100 Subject: [PATCH 0188/1444] New translations setup-linux.md (German) --- .../current/gaia/setup-linux.md | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) 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 index db427f890a..2c0ca2b92e 100644 --- a/i18n/de/docusaurus-plugin-content-docs/current/gaia/setup-linux.md +++ b/i18n/de/docusaurus-plugin-content-docs/current/gaia/setup-linux.md @@ -1,6 +1,6 @@ --- 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. +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 @@ -19,8 +19,7 @@ This configuration will setup the following 4 docker containers: 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: +**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 @@ -48,8 +47,7 @@ chmod +x ${DESTINATION_DC}/docker-compose 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. +**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 From 35de9c795353a96b413985c262e6924072c5c49d Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:40:08 +0100 Subject: [PATCH 0189/1444] New translations digitalocean.md (German) --- .../current/nodes-and-miners/digitalocean.md | 41 +++++++++++-------- 1 file changed, 25 insertions(+), 16 deletions(-) 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 index dd7194f504..15df918d04 100644 --- 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 @@ -1,28 +1,30 @@ --- -title: Stacks on DigitalOcean +title: Run a Node with Digital Ocean description: A guide to setup Stacks on DigitalOcean -sidebar_position: 4 +sidebar_position: 2 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). +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`. +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 plan that meets the minimum requirements) and your prefered datacenter region. ![](/img/sh_digitalocean-choose-plan.png) +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 if your prefer. +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) @@ -46,41 +48,48 @@ Congratulations! You are now running the Stacks Blockchain. You can click on `Co ## 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). +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`. -Once the stacks blockchain starts to sync with peers, application ports will open and nginx port 80 will now start proxying requests. +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 v3.0.3 (master:cd0c8aef)", + "server_version": "stacks-blockchain-api v6.2.3 (master:77ab3ae2)", "status": "ready", "chain_tip": { - "block_height": 16220, - "block_hash": "0x3123fba9c0de6b569573494cf83c1d5d198a66bfd5f48ef97949b6bf11ba13be", - "index_block_hash": "0xeec960fbbd6186b4ccac85ce12adba72be497d881f81e077305c90955b51a6ae" + "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/README.md#quickstart). +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). -## API Creation +## 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 -curl -X POST -H 'Content-Type: application/json' \ +$ export TOKEN= +$ 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"}' \ + '{"name":"stacks-blockchain","region":"sfo2","size":"s-2vcpu-4gb","image":"stacksfoundation-stacksblockchain"}' \ "https://api.digitalocean.com/v2/droplets" ``` From 5e4424277d475a81bb7b9998bb6856c25f073c61 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:40:09 +0100 Subject: [PATCH 0190/1444] New translations index.md (German) --- .../current/nodes-and-miners/index.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) 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 index b6cbb9754a..e5f4f2c250 100644 --- 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 @@ -1,11 +1,11 @@ --- title: Nodes and Miners description: Nodes and Miners -sidebar_position: 7 +sidebar_position: 5 --- -Here are all the steps to run nodes and miners, both on mainnet and testnet. +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. -## What's a Stacks node? +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. -## What's a Stacks miner? +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. From 72b93121c53231bdf53fa453d23eef0d7f1832d3 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:40:10 +0100 Subject: [PATCH 0191/1444] New translations miner-mainnet.md (German) --- .../current/nodes-and-miners/miner-mainnet.md | 384 +++++------------- 1 file changed, 108 insertions(+), 276 deletions(-) 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 index 59528c33e1..5afd34c23f 100644 --- 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 @@ -1,195 +1,100 @@ --- title: Mine mainnet Stacks tokens -description: Set up and run a miner on the Stacks 2.0 mainnet -sidebar_position: 5 +description: Set up and run a miner on Stacks Mainnet +sidebar_position: 6 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. +For more on the technical details of mining, please review the [mining guide](../stacks-academy/mining) -If you're interested in mining on the testnet, you can find instructions on how to do that [here](miner-testnet): +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 want to learn more about the technical details of mining, please review the [mining guide](../understand-stacks/mining): +If you're interested in mining on the Stacks testnet, you can find instructions on how to do that [here](miner-testnet): -## Running bitcoind locally +## Running a Bitcoin Mainnet Full Node -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) +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. -First, download the bitcoind software for your platform from https://bitcoin.org/en/download. +- [Ensure your computer meets the minimum hardware requirements before continuing.](https://bitcoin.org/en/bitcoin-core/features/requirements#system-requirements) -Next, start bitcoind with the following configuration: +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): -```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. +:::tip It is recommened to use a persistent location for the chainstate, in the steps below we're using `/bitcoin` ::: -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 -``` +### Update the Bitcoin Configuration File - +Next, update the bitcoin configuration: -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: +- **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 -[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 = "" -... +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 ``` -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. +### Start Bitcoin -To run your miner, run this in the command line: +Finally, start bitcoin as follows (adjust the `conf` path to where it was created in the previous step, i.e. `$HOME/bitcoin.conf`): ```bash -stacks-node start --config=./testnet/stacks-node/conf/mainnet-miner-conf.toml +bitcoind -conf=$HOME/bitcoin.conf ``` -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 -``` +:::note +It will take a few days for the node to synchronize with Bitcoin mainnet. +::: -The above code will compile an optimized binary. To use it, run: +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 -cd ../.. -./target/release/stacks-node start --config=./mainnet-miner-conf.toml +$ bitcoin-cli \ + -rpcconnect=localhost \ + -rpcport=8332 \ + -rpcuser=btcuser \ + -rpcpassword=btcpassword \ +getblockchaininfo | jq .blocks +773281 ``` -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 +## Running a Stacks Blockchain miner -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: +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) -```bash -STACKS_LOG_DEBUG=1 stacks-node mainnet -``` +_There may be some extra requirements to building, [defined here](https://github.com/stacksfoundation/miner-docs/blob/main/prerequisites.md#install-required-packages)_ -## Running a miner in Windows +:::tip It is recommened to use a persistent location for the chainstate, in the steps below we're using `/stacks-blockchain` ::: -### Prerequisites +### Generate a keychain -Make sure are [running a node](run-a-node) and [running bitcoind locally](#running-bitcoind-locally) before starting this tutorial. +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. -### 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: +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 -npm install --global @stacks/cli -stx make_keychain > cli_keychain.json -type cli_keychain.json +npx @stacks/cli make_keychain 2>/dev/null | jq -r ``` -After this runs, you'll probably see some installation logs, and at the end you should see some JSON that looks like this: +After this runs, you should see some JSON printed to the screen that looks like this: ```json { @@ -203,167 +108,99 @@ After this runs, you'll probably see some installation logs, and at the end you } ``` -:::tip Check out the [Stacks CLI reference](https://docs.hiro.so/references/stacks-cli) for more details ::: +:::warning **Do not lose this information** - we'll need to use the `privateKey` and `btcAddress` fields in later steps. ::: -The above BTC address will then need to be imported into the BTC network. +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=your-user -rpcpassword=your-password importaddress +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 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 Stacks Blockchain Configuration File -Update the following properties: +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`. -```toml -[node] -... -[node] -... -# Enter your private key here -seed = "replace-with-your-private-key" -local_peer_seed = "replace-with-your-private-key" -... +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. -[burnchain] -... -[node] -... -# Enter your private key here -seed = "replace-with-your-private-key" -local_peer_seed = "replace-with-your-private-key" -... +Next, update the bitcoin configuration: -[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 = "" -... +- **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`) -[burnchain] -... +```toml [node] -... -# Enter your private key here -seed = "replace-with-your-private-key" -local_peer_seed = "replace-with-your-private-key" -... +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] -... -# To mine on mainnet, you need to run bitcoind locally -# Details can be found in above section, 'Running bitcoind locally' +chain = "bitcoin" +mode = "mainnet" peer_host = "127.0.0.1" -username = "" -password = "" -... +username = "" +password = "" +rpc_port = 8332 +peer_port = 8333 +satoshis_per_byte = 100 +burn_fee_cap = 20000 ``` -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 +### Start the Stacks Blockchain -To start your miner, run this in the command line: +To run your miner, run this in the command line: ```bash -stacks-node start --config=testnet/stacks-node/conf/mainnet-miner-conf.toml +stacks-node start --config=$HOME/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 +### 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 -set RUST_BACKTRACE=full; -set STACKS_LOG_DEBUG=1; -stacks-node start --config=mainnet-miner-conf.toml +STACKS_LOG_DEBUG=1 stacks-node start --config=$HOME/mainnet-miner-conf.toml ``` -## Optional: Running with Docker +--- + +## Optional: Running a Stacks Blockchain miner with Docker -Alternatively, you can run the mainnet node with Docker. +Alternatively, you can run a Stacks mainnet miner with Docker. -:::caution Ensure you have [Docker](https://docs.docker.com/get-docker/) installed on your machine. ::: +:::caution Ensure you have [Docker](https://docs.docker.com/get-docker/) installed. ::: -### Generate keychain and get tokens +### 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 +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 crytpocurrency exchange such as [Coinbase](https://www.coinbase.com), [Binance](https://www.binance.com), or [Kraken](https://www.kraken.com). - -### Update configuration file +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). -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 Stacks Blockchain Docker Configuration File -Update the following properties: +Use the steps oulined above to create the [configuration file](miner-mainnet#update-the-stacks-blockchain-configuration-file) -```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 +### 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 ::: @@ -374,7 +211,8 @@ docker run -d \ --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" \ + -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 \ @@ -389,9 +227,9 @@ 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). +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 on your machine: +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) @@ -400,13 +238,7 @@ Ensure you have the following prerequisites installed on your machine: ### 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). +Use the steps [outlined above](miner-mainnet#generate-a-keychain-and-get-some-tokens) ### Install the chart and run the miner From 968e0a1a74c8914dc5d68e810b289dce5a45088a Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:40:11 +0100 Subject: [PATCH 0192/1444] New translations miner-testnet.md (German) --- .../current/nodes-and-miners/miner-testnet.md | 395 ++++++------------ 1 file changed, 128 insertions(+), 267 deletions(-) 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 index 3e2343d344..c0a27e63d5 100644 --- 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 @@ -1,35 +1,52 @@ --- title: Mine testnet Stacks tokens -description: Set up and run a miner on the Stacks 2.0 testnet -sidebar_position: 4 +description: Set up and run a miner on Stacks Testnet +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 testnet. +For more on the technical details of mining, please review the [mining guide](../stacks-academy/mining) -If you want to learn more about the technical details of mining, please review the [mining guide](../understand-stacks/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)). -## Running bitcoind locally +If you're interested in mining on the Stacks mainnet, you can find instructions on how to do that [here](miner-mainnet): -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) +## Running a Bitcoin Testnet Full Node -First, download the bitcoind software for your platform from https://bitcoin.org/en/download. +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. -Next, start bitcoind with the following configuration: +- [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 -rpcuser=your-bitcoind-username -rpcpassword=your-bitcoind-password testnet=1 -txindex=0 -listen=1 -rpcserialversion=0 -maxorphantx=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 @@ -37,153 +54,51 @@ 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. +### Start Bitcoin -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: +Finally, start bitcoind as follows: ```bash -stacks-node start --config=./testnet/stacks-node/conf/testnet-miner-conf.toml +bitcoind -conf=$HOME/bitcoin.conf ``` -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 -``` +:::note +It will take a few hours for the node to synchronize with Bitcoin testnet. +::: -The above code will compile an optimized binary. To use it, run: +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 -cd ../.. -./target/release/stacks-node start --config=./testnet/conf/testnet-follower-conf.toml +$ bitcoin-cli \ + -rpcconnect=localhost \ + -rpcport=18332 \ + -rpcuser=btcuser \ + -rpcpassword=btcpass \ +getblockchaininfo | jq .blocks +2417570 ``` -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 +## Running a Stacks Blockchain miner -### Prerequisites +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) -Make sure are [running a testnet node](run-a-node) before starting this tutorial. +_There may be some extra requirements to building, [defined here](https://github.com/stacksfoundation/miner-docs/blob/main/prerequisites.md#install-required-packages)_ -### Generate keychain and get testnet tokens in Windows +:::tip It is recommened to use a persistent location for the chainstate, in the steps below we're using `/stacks-blockchain` ::: -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. +### Generate a keychain -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. +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. -Generate a keychain: +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 -npm install --global @stacks/cli -stx make_keychain -t > cli_keychain.json -type cli_keychain.json +npx @stacks/cli make_keychain -t 2>/dev/null | jq -r ``` -After this runs, you'll probably see some installation logs, and at the end you should see some JSON that looks like this: +After this runs, you should see some JSON printed to the screen that looks like this: ```json { @@ -197,161 +112,110 @@ After this runs, you'll probably see some installation logs, and at the end you } ``` -:::tip Check out the [Stacks CLI reference](https://docs.hiro.so/references/stacks-cli) for more details ::: +:::warning **Do not lose this information** - we'll need to use the `privateKey` and `btcAddress` fields in later steps. ::: -Request BTC from faucet: +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 ::: -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/). +```bash +bitcoin-cli \ + -rpcport=18332 \ + -rpcuser=btcuser \ + -rpcpassword=btcpassword \ +importaddress +``` -### Update configuration file +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 Stacks Blockchain Configuration File -Update the following properties: +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`. -```toml -[node] -... -[node] -... -seed = "replace-with-your-private-key" -local_peer_seed = "replace-with-your-private-key" -... +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. -[burnchain] -... -[node] -... -seed = "replace-with-your-private-key" -local_peer_seed = "replace-with-your-private-key" -... +Next, update the bitcoin configuration: -[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 = "" -... +- **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`) -[burnchain] -... +```toml [node] -... -seed = "replace-with-your-private-key" -local_peer_seed = "replace-with-your-private-key" -... +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] -... -# To mine on Testnet, you need to run bitcoind locally -# Details can be found in above section, 'Running bitcoind locally' +chain = "bitcoin" +mode = "xenon" peer_host = "127.0.0.1" -username = "" -password = "" -... +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 ``` -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 +### Start the Stacks Blockchain -To start your miner, run this in the command line: +To run your miner, run this in the command line: ```bash -stacks-node start --config=testnet/stacks-node/conf/testnet-miner-conf.toml +stacks-node start --config=$HOME/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 +### 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 -set RUST_BACKTRACE=full; -set STACKS_LOG_DEBUG=1; -stacks-node start --config=testnet-miner-conf.toml +STACKS_LOG_DEBUG=1 stacks-node start --config=$HOME/testnet-miner-conf.toml ``` -## Optional: Running with Docker +--- + +## Optional: Running a Stacks Blockchain miner with Docker -Alternatively, you can run the testnet node with Docker. +Alternatively, you can run a Stacks testnet miner with Docker. -:::warning Ensure you have [Docker](https://docs.docker.com/get-docker/) installed on your machine. ::: +:::caution Ensure you have [Docker](https://docs.docker.com/get-docker/) installed ::: -### Generate keychain and get testnet tokens +### Generate a Keychain and Get Some Tokens Generate a keychain: ```bash -docker run -i node:14-alpine npx @stacks/cli make_keychain -t 2>/dev/null +docker run -i node:14-alpine npx @stacks/cli make_keychain 2>/dev/null | jq -r ``` -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" -... +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. -[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 = "" -... -``` +### Update Stacks Blockchain Docker Configuration File -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. +Use the steps oulined above to create the [configuration file](miner-testnet#update-the-stacks-blockchain-configuration-file) -### Start the miner +### 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 ::: @@ -362,7 +226,8 @@ docker run -d \ --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" \ + -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 \ @@ -375,26 +240,22 @@ You can review the node logs with this command: 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). +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 on your machine: +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 testnet tokens - -Generate a keychain: - -```bash -docker run -i node:14-alpine npx @stacks/cli make_keychain -t 2>/dev/null -``` +### Generate keychain and get some tokens -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/). +Use the steps [outlined above](miner-testnet#generate-a-keychain-and-get-some-tokens) ### Install the chart and run the miner @@ -405,7 +266,7 @@ 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.node.seed="replace-with-your-privateKey-from-generate-keychain-step" \ ``` You can review the node logs with this command: From c2cc2a4cad13eceaa58c3d2da61346af6dfd1a4f Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:40:12 +0100 Subject: [PATCH 0193/1444] New translations stacks-node-configuration.md (German) --- .../stacks-node-configuration.md | 158 +++++++++++------- 1 file changed, 101 insertions(+), 57 deletions(-) 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 index 89af343dc6..cd216e7103 100644 --- 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 @@ -1,7 +1,7 @@ --- title: Stacks Node Configuration description: Configuration parameters and options for the stacks-node binary -sidebar_position: 6 +sidebar_position: 4 --- ## Usage @@ -10,97 +10,141 @@ sidebar_position: 6 stacks-node sub-command [--subcommand-option ] ``` -## Subcommands +### 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 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 -### mocknet +## Configuration File Options -Start a node based on a fast local setup emulating a burnchain. Ideal for smart contract development. +The Stacks Blockchain configuration file has multiple sections under which an option may be placed. -Example: +- [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) -```bash -stacks-node mocknet -``` +For reference, several configuration file examples are [available here](https://github.com/stacks-network/stacks-blockchain/tree/master/testnet/stacks-node/conf) -### krypton +- [Example mainnet follower configuration](./stacks-node-configuration#example-mainnet-follower-configuration) -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). +### node -Example: +Contains various configuration options for the stacks-node binary. -```bash -stacks-node krypton -``` +| 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. | -### testnet +### events_observer -Start a node that will join and stream blocks from the public testnet. +:::info This section is _optional_ and not required -Example: +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. -```bash -stacks-node testnet -``` +| 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. | | -### mainnet +### connection_options -Start a node that joins and streams blocks from the public mainnet. +:::info This section is _optional_ and not required. -Example: +However, if this section is added, **all** fields are required ::: -```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. +Specifies configuration options for others connecting to the stacks node. -#### Arguments +| 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 | -**--config**: relative or absolute path to the TOML config file. Required. +### burnchain -Example: +This section contains configuration options pertaining to the blockchain the stacks-node binds to on the backend for proof-of-transfer (BTC). -```bash -stacks-node start --config=/path/to/config.toml -``` +| 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` | -See [Configuration File Options](#configuration-file-options) for more information. +#### Mining -#### version +| 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`. | -Displays information about the current version and the release cycle. +### ustx_balance -Example: +- `mocknet`/`testnet` only -```bash -stacks-node version -``` +This section contains configuration options allocating microSTX per address in the genesis block -#### help +This section can repeat multiple times, but each section can only define a single address. -Displays a help message. +:::info This section is only required for the `testnet` and `mocknet` networks. -Example: +However, if this section is added, **all** fields are required ::: -```bash -stacks-node help -``` +| 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 | -## Configuration File Options +## Example Mainnet Follower Configuration -The TOML configuration file has multiple sections under which an option may be placed. +```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" -To see a list of example configurations, [please see this page](https://github.com/stacks-network/stacks-blockchain/tree/master/testnet/stacks-node/conf). +[burnchain] +chain = "bitcoin" +mode = "mainnet" +peer_host = "localhost" +username = "user" +password = "pass" +rpc_port = 8332 +peer_port = 8333 -### Section: node +[[events_observer]] +endpoint = "localhost:3700" +retry_count = 255 +events_keys = ["*"] +``` -Contains various configuration options pertaining to the stacks-node. -Example: + From d08b7bc5795f5c7d538db8516de69c8c31e934d2 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:40:13 +0100 Subject: [PATCH 0194/1444] New translations accounts.md (German) --- .../current/stacks-academy/accounts.md | 215 ++++++++++++++++++ 1 file changed, 215 insertions(+) create mode 100644 i18n/de/docusaurus-plugin-content-docs/current/stacks-academy/accounts.md diff --git a/i18n/de/docusaurus-plugin-content-docs/current/stacks-academy/accounts.md b/i18n/de/docusaurus-plugin-content-docs/current/stacks-academy/accounts.md new file mode 100644 index 0000000000..55d0165def --- /dev/null +++ b/i18n/de/docusaurus-plugin-content-docs/current/stacks-academy/accounts.md @@ -0,0 +1,215 @@ +--- +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" + } + } + ] +} +``` From 8940504743be52229bfbe489adcc5872a27daf34 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:40:14 +0100 Subject: [PATCH 0195/1444] New translations microblocks.md (German) --- .../current/stacks-academy/microblocks.md | 107 ++++++++++++++++++ 1 file changed, 107 insertions(+) create mode 100644 i18n/de/docusaurus-plugin-content-docs/current/stacks-academy/microblocks.md diff --git a/i18n/de/docusaurus-plugin-content-docs/current/stacks-academy/microblocks.md b/i18n/de/docusaurus-plugin-content-docs/current/stacks-academy/microblocks.md new file mode 100644 index 0000000000..9310aa65be --- /dev/null +++ b/i18n/de/docusaurus-plugin-content-docs/current/stacks-academy/microblocks.md @@ -0,0 +1,107 @@ +--- +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. + +[provides an endpoint]: https://docs.hiro.so/get-started/stacks-blockchain-api#nonce-handling +[microblocks_api]: https://docs.hiro.so/api#tag/Microblocks From a254e81d66cd8d90ab483aea2505c33b114fe61e Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:40:15 +0100 Subject: [PATCH 0196/1444] New translations mining.md (German) --- .../current/stacks-academy/mining.md | 84 +++++++++++++++++++ 1 file changed, 84 insertions(+) create mode 100644 i18n/de/docusaurus-plugin-content-docs/current/stacks-academy/mining.md diff --git a/i18n/de/docusaurus-plugin-content-docs/current/stacks-academy/mining.md b/i18n/de/docusaurus-plugin-content-docs/current/stacks-academy/mining.md new file mode 100644 index 0000000000..e6e93e130a --- /dev/null +++ b/i18n/de/docusaurus-plugin-content-docs/current/stacks-academy/mining.md @@ -0,0 +1,84 @@ +--- +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 From 677519309f2741b73ab83109d5e122ee2659c2c1 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:40:16 +0100 Subject: [PATCH 0197/1444] New translations network.md (German) --- .../current/stacks-academy/network.md | 151 ++++++++++++++++++ 1 file changed, 151 insertions(+) create mode 100644 i18n/de/docusaurus-plugin-content-docs/current/stacks-academy/network.md diff --git a/i18n/de/docusaurus-plugin-content-docs/current/stacks-academy/network.md b/i18n/de/docusaurus-plugin-content-docs/current/stacks-academy/network.md new file mode 100644 index 0000000000..dd50cb7ee1 --- /dev/null +++ b/i18n/de/docusaurus-plugin-content-docs/current/stacks-academy/network.md @@ -0,0 +1,151 @@ +--- +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 +} +``` From 19743707bc8ca8ad203f203025ad2f8518e5184d Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:40:17 +0100 Subject: [PATCH 0198/1444] New translations stacking.md (German) --- .../current/stacks-academy/stacking.md | 151 ++++++++++++++++++ 1 file changed, 151 insertions(+) create mode 100644 i18n/de/docusaurus-plugin-content-docs/current/stacks-academy/stacking.md diff --git a/i18n/de/docusaurus-plugin-content-docs/current/stacks-academy/stacking.md b/i18n/de/docusaurus-plugin-content-docs/current/stacks-academy/stacking.md new file mode 100644 index 0000000000..545f538ecb --- /dev/null +++ b/i18n/de/docusaurus-plugin-content-docs/current/stacks-academy/stacking.md @@ -0,0 +1,151 @@ +--- +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. 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. + +![](/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 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 (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 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) From 49bcc1129fb0203f84b247ad53a68df5d15658dd Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:40:17 +0100 Subject: [PATCH 0199/1444] New translations technical-specs.md (German) --- .../current/stacks-academy/technical-specs.md | 79 +++++++++++++++++++ 1 file changed, 79 insertions(+) create mode 100644 i18n/de/docusaurus-plugin-content-docs/current/stacks-academy/technical-specs.md diff --git a/i18n/de/docusaurus-plugin-content-docs/current/stacks-academy/technical-specs.md b/i18n/de/docusaurus-plugin-content-docs/current/stacks-academy/technical-specs.md new file mode 100644 index 0000000000..695f849e1a --- /dev/null +++ b/i18n/de/docusaurus-plugin-content-docs/current/stacks-academy/technical-specs.md @@ -0,0 +1,79 @@ +--- +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). +- 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 whitepaper v2](https://www.youtube.com/watch?v=Wd-Bfe8Sn-Y). From fa01e81f75c214a32c091b3c00b5c4de3c67ed74 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:40:18 +0100 Subject: [PATCH 0200/1444] New translations testnet.md (German) --- .../current/stacks-academy/testnet.md | 35 +++++++++++++++++++ 1 file changed, 35 insertions(+) create mode 100644 i18n/de/docusaurus-plugin-content-docs/current/stacks-academy/testnet.md diff --git a/i18n/de/docusaurus-plugin-content-docs/current/stacks-academy/testnet.md b/i18n/de/docusaurus-plugin-content-docs/current/stacks-academy/testnet.md new file mode 100644 index 0000000000..f8b9f03df2 --- /dev/null +++ b/i18n/de/docusaurus-plugin-content-docs/current/stacks-academy/testnet.md @@ -0,0 +1,35 @@ +--- +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. + +### 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) From 2d3afd558b32ff4d7de57e531be12ac06702304d Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:40:19 +0100 Subject: [PATCH 0201/1444] New translations transactions.md (German) --- .../current/stacks-academy/transactions.md | 40 +++++++++++++++++++ 1 file changed, 40 insertions(+) create mode 100644 i18n/de/docusaurus-plugin-content-docs/current/stacks-academy/transactions.md diff --git a/i18n/de/docusaurus-plugin-content-docs/current/stacks-academy/transactions.md b/i18n/de/docusaurus-plugin-content-docs/current/stacks-academy/transactions.md new file mode 100644 index 0000000000..ba6b18f0f7 --- /dev/null +++ b/i18n/de/docusaurus-plugin-content-docs/current/stacks-academy/transactions.md @@ -0,0 +1,40 @@ +--- +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). ::: From d0a9f4e2c6dd9f6a0dae709c039bc75f896b0580 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:40:21 +0100 Subject: [PATCH 0202/1444] New translations language-functions.md (German) --- .../current/clarity/language-functions.md | 2031 +++++++++++++++++ 1 file changed, 2031 insertions(+) create mode 100644 i18n/de/docusaurus-plugin-content-docs/current/clarity/language-functions.md diff --git a/i18n/de/docusaurus-plugin-content-docs/current/clarity/language-functions.md b/i18n/de/docusaurus-plugin-content-docs/current/clarity/language-functions.md new file mode 100644 index 0000000000..c83c864810 --- /dev/null +++ b/i18n/de/docusaurus-plugin-content-docs/current/clarity/language-functions.md @@ -0,0 +1,2031 @@ +--- +title: Functions +description: See a detailed list of all functions for the Clarity language. +sidebar_position: 3 +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: + +#### 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-existent\"))))) ;; 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-existent\") ;; 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-existent\" })) ;; 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-existent\" }))) ;; 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-existent\" }))) ;; 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 \"Stacks\" '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 successfully 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_ transferred from another principal, but rather minted. + +If a non-positive amount is provided to mint, this function returns `(err 1)`. Otherwise, on successfully 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_ transferred 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 successfully 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 successfully 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)) +``` From 718beb201eadac18c009c0002b8265cde18559c4 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:40:22 +0100 Subject: [PATCH 0203/1444] New translations language-keywords.md (German) --- .../current/clarity/language-keywords.md | 146 ++++++++++++++++++ 1 file changed, 146 insertions(+) create mode 100644 i18n/de/docusaurus-plugin-content-docs/current/clarity/language-keywords.md diff --git a/i18n/de/docusaurus-plugin-content-docs/current/clarity/language-keywords.md b/i18n/de/docusaurus-plugin-content-docs/current/clarity/language-keywords.md new file mode 100644 index 0000000000..1aca5359c3 --- /dev/null +++ b/i18n/de/docusaurus-plugin-content-docs/current/clarity/language-keywords.md @@ -0,0 +1,146 @@ +--- +title: Keywords +description: See a detailed list of all keywords for the Clarity language. +sidebar_position: 4 +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 +``` From 51720aaf11cfe79a52738e276e487ead831388bb Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:40:23 +0100 Subject: [PATCH 0204/1444] New translations language-types.md (German) --- .../current/clarity/language-types.md | 25 +++++++++++++++++++ 1 file changed, 25 insertions(+) create mode 100644 i18n/de/docusaurus-plugin-content-docs/current/clarity/language-types.md diff --git a/i18n/de/docusaurus-plugin-content-docs/current/clarity/language-types.md b/i18n/de/docusaurus-plugin-content-docs/current/clarity/language-types.md new file mode 100644 index 0000000000..0af4577dc9 --- /dev/null +++ b/i18n/de/docusaurus-plugin-content-docs/current/clarity/language-types.md @@ -0,0 +1,25 @@ +--- +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. | From 4fb23267e0dbb47966991f2a70744eae0571d9f1 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:40:24 +0100 Subject: [PATCH 0205/1444] New translations miner-costs-and-fees.md (German) --- .../current/nodes-and-miners/miner-costs-and-fees.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) 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 index 40397a51e0..dd8ee721cc 100644 --- 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 @@ -8,7 +8,7 @@ sidebar_position: 8 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 @@ -22,3 +22,5 @@ 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). From a116b1199890f29d29b22241e87ebcdee9fab7e5 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:40:25 +0100 Subject: [PATCH 0206/1444] New translations verify-miner.md (German) --- .../current/nodes-and-miners/verify-miner.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) 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 index 094e3f03a1..18e8dd3a48 100644 --- 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 @@ -7,7 +7,7 @@ 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 +$ 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 -``` \ No newline at end of file +``` From 55ff8ea3147e9aeee7fde22ce6b1d1874991b109 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:40:26 +0100 Subject: [PATCH 0207/1444] New translations stacks-blockchain-api.md (German) --- .../stacks-academy/stacks-blockchain-api.md | 41 +++++++++++++++++++ 1 file changed, 41 insertions(+) create mode 100644 i18n/de/docusaurus-plugin-content-docs/current/stacks-academy/stacks-blockchain-api.md diff --git a/i18n/de/docusaurus-plugin-content-docs/current/stacks-academy/stacks-blockchain-api.md b/i18n/de/docusaurus-plugin-content-docs/current/stacks-academy/stacks-blockchain-api.md new file mode 100644 index 0000000000..ad9bb1822e --- /dev/null +++ b/i18n/de/docusaurus-plugin-content-docs/current/stacks-academy/stacks-blockchain-api.md @@ -0,0 +1,41 @@ +--- +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`. ::: From 6ba3a0dc80327f69c9f2564ac652546d5dd82ec2 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:40:27 +0100 Subject: [PATCH 0208/1444] New translations run-a-node.md (German) --- .../current/nodes-and-miners/run-a-node.md | 329 +++--------------- 1 file changed, 42 insertions(+), 287 deletions(-) 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 index 94d938c5ca..2993568ce4 100644 --- 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 @@ -1,5 +1,5 @@ --- -title: Run a node +title: Run a Node with Docker description: Set up and run a Stacks node sidebar_position: 1 tags: @@ -8,344 +8,99 @@ tags: ## Stacks Blockchain with Docker -Run your own Stacks Blockchain node easily with just few commands. +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) -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](./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) -## **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 -``` +## **Requirements:** -- With optional proxy: +The **minimum viable requirements** are listed below. -```bash -./manage.sh -n -a start -f proxy -``` +While you _can_ run a node using these specs, it's _recommended_ to assign more than the minimum for better performance. -- With optional bitcoin node: +- ⚠️ [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_ ) -```bash -./manage.sh -n -a start -f bitcoin -``` +:::caution MacOS with an ARM processor is NOT recommended -5. **Stop the Services** +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. ::: -```bash -./manage.sh -n -a stop -``` - -6. **Retrieve Service Logs** - -```bash -./manage.sh -n -a logs -``` - -- Export docker log files to `./exported-logs`: +## **Quickstart** -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. +The `` placeholder used below can be replaced with one of: -```bash -./manage.sh -n -a logs export -``` +- mainnet +- testnet +- mocknet -7. **Restart all services** +1. **Clone the stacks-blockchain-docker repository locally** ```bash -./manage.sh -n -a restart +git clone https://github.com/stacks-network/stacks-blockchain-docker && cd stacks-blockchain-docker ``` -- With optional proxy: +2. **Start the Services** ```bash -./manage.sh -n -a restart -f proxy +./manage.sh -n -a start ``` -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. +:::note With an optional HTTP proxy on port 80: ```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. - +./manage.sh -n -a start -f proxy ``` -9. **Download BNS data to** `./persistent-data/bns-data` - -```bash -./manage.sh bns -``` +::: -10. **Export stacks-blockchain-api events** (_Not applicable for mocknet_) +## **Accessing the services** -```bash -./manage.sh -n -a export -# check logs for completion -./manage.sh -n -a restart -``` +:::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. -11. **Replay stacks-blockchain-api events** (_Not applicable for mocknet_) +Follow the logs to track the sync progress: ```bash -./manage.sh -n -a import -# check logs for completion -./manage.sh -n -a restart +./manage.sh -n -a logs ``` -## **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` +- Ports `20443-20444` are exposed on `localhost` ```bash -curl -sL localhost:20443/v2/info | jq +curl -sL localhost:20443/v2/info | jq -r ``` **stacks-blockchain-api**: -- Port `3999` are exposed to `localhost` +- Port `3999` is exposed on `localhost` ```bash -curl -sL localhost:3999/v2/info | jq +curl -sL localhost:3999 | jq -r ``` **proxy**: -- Port `80` is exposed to `localhost` +- Port `80` is exposed on `localhost` ```bash -curl -sL localhost/v2/info | jq -curl -sL localhost/ | jq +curl -sL localhost/v2/info | jq -r +curl -sL localhost | jq -r ``` --- ## 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 -``` +:::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): ::: --- - -## **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 From 3a29b7f596adbee7ee41dac5f3bd7660c44ea03a Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:40:28 +0100 Subject: [PATCH 0209/1444] New translations index.md (German) --- .../current/clarity/index.md | 58 +++++++++++++++++++ 1 file changed, 58 insertions(+) create mode 100644 i18n/de/docusaurus-plugin-content-docs/current/clarity/index.md diff --git a/i18n/de/docusaurus-plugin-content-docs/current/clarity/index.md b/i18n/de/docusaurus-plugin-content-docs/current/clarity/index.md new file mode 100644 index 0000000000..903de93a45 --- /dev/null +++ b/i18n/de/docusaurus-plugin-content-docs/current/clarity/index.md @@ -0,0 +1,58 @@ +--- +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?2 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. If you are unsure what this means, let it not worry you for now. The serious advantage of decidability will become more apparent over time. + +### 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. From 8fa9b92ca1ff1b5b7695247b7e0328f0b3d497b6 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:40:28 +0100 Subject: [PATCH 0210/1444] New translations index.md (German) --- .../current/stacks-academy/index.md | 11 +++++++++++ 1 file changed, 11 insertions(+) create mode 100644 i18n/de/docusaurus-plugin-content-docs/current/stacks-academy/index.md diff --git a/i18n/de/docusaurus-plugin-content-docs/current/stacks-academy/index.md b/i18n/de/docusaurus-plugin-content-docs/current/stacks-academy/index.md new file mode 100644 index 0000000000..a5bdb3c790 --- /dev/null +++ b/i18n/de/docusaurus-plugin-content-docs/current/stacks-academy/index.md @@ -0,0 +1,11 @@ +--- +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. From 72bd4841532c1112b90f361310010cc770c55f7c Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:40:29 +0100 Subject: [PATCH 0211/1444] New translations proof-of-transfer.md (German) --- .../stacks-academy/proof-of-transfer.md | 83 +++++++++++++++++++ 1 file changed, 83 insertions(+) create mode 100644 i18n/de/docusaurus-plugin-content-docs/current/stacks-academy/proof-of-transfer.md diff --git a/i18n/de/docusaurus-plugin-content-docs/current/stacks-academy/proof-of-transfer.md b/i18n/de/docusaurus-plugin-content-docs/current/stacks-academy/proof-of-transfer.md new file mode 100644 index 0000000000..50f4b739d6 --- /dev/null +++ b/i18n/de/docusaurus-plugin-content-docs/current/stacks-academy/proof-of-transfer.md @@ -0,0 +1,83 @@ +--- +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. From b46306f3a06fa551edad7214e28da07530361a4c Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:40:30 +0100 Subject: [PATCH 0212/1444] New translations what-is-stacks.md (German) --- .../current/stacks-academy/what-is-stacks.md | 102 ++++++++++++++++++ 1 file changed, 102 insertions(+) create mode 100644 i18n/de/docusaurus-plugin-content-docs/current/stacks-academy/what-is-stacks.md diff --git a/i18n/de/docusaurus-plugin-content-docs/current/stacks-academy/what-is-stacks.md b/i18n/de/docusaurus-plugin-content-docs/current/stacks-academy/what-is-stacks.md new file mode 100644 index 0000000000..94277da8a9 --- /dev/null +++ b/i18n/de/docusaurus-plugin-content-docs/current/stacks-academy/what-is-stacks.md @@ -0,0 +1,102 @@ +--- +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. + +There's a lot of jargon, possible assumptions, controversy, and cool technology wrapped up in those statements. So let's get started by getting a 30,000 foot view of what exactly Stacks is. + +## Stacks Explained in (Slightly Less Than) 10 Minutes + +
+ +
+ +## 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, Stacks takes a different approach. + +## 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). + +By taking this 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 with some unique properties, like having its own token, that allow it to maintain a historical ledger of all of its transactions and operate with its own security budget. + +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_. + +Nope. 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. From 14abff3dd6a05c17acd74a5da581de67abca5b2b Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:40:31 +0100 Subject: [PATCH 0213/1444] New translations community-tutorials.md (German) --- .../current/tutorials/community-tutorials.md | 24 +++++++++++++++++++ 1 file changed, 24 insertions(+) create mode 100644 i18n/de/docusaurus-plugin-content-docs/current/tutorials/community-tutorials.md diff --git a/i18n/de/docusaurus-plugin-content-docs/current/tutorials/community-tutorials.md b/i18n/de/docusaurus-plugin-content-docs/current/tutorials/community-tutorials.md new file mode 100644 index 0000000000..a4f3d970ca --- /dev/null +++ b/i18n/de/docusaurus-plugin-content-docs/current/tutorials/community-tutorials.md @@ -0,0 +1,24 @@ +--- +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/) From 8522ae824a76ce28dd6dc8a873d6f3b22e3b900c Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:40:32 +0100 Subject: [PATCH 0214/1444] New translations hello-stacks.md (German) --- .../current/tutorials/hello-stacks.md | 759 ++++++++++++++++++ 1 file changed, 759 insertions(+) create mode 100644 i18n/de/docusaurus-plugin-content-docs/current/tutorials/hello-stacks.md diff --git a/i18n/de/docusaurus-plugin-content-docs/current/tutorials/hello-stacks.md b/i18n/de/docusaurus-plugin-content-docs/current/tutorials/hello-stacks.md new file mode 100644 index 0000000000..a0a442d135 --- /dev/null +++ b/i18n/de/docusaurus-plugin-content-docs/current/tutorials/hello-stacks.md @@ -0,0 +1,759 @@ +--- +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. From e8bcba55344c65dfc6681d6962a9eac6263e2d8b Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:40:33 +0100 Subject: [PATCH 0215/1444] New translations index.md (German) --- .../current/tutorials/index.md | 11 +++++++++++ 1 file changed, 11 insertions(+) create mode 100644 i18n/de/docusaurus-plugin-content-docs/current/tutorials/index.md diff --git a/i18n/de/docusaurus-plugin-content-docs/current/tutorials/index.md b/i18n/de/docusaurus-plugin-content-docs/current/tutorials/index.md new file mode 100644 index 0000000000..1d544c7bc1 --- /dev/null +++ b/i18n/de/docusaurus-plugin-content-docs/current/tutorials/index.md @@ -0,0 +1,11 @@ +--- +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. From 90560ceb142fe5a7865251b04d0d020251507056 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:40:34 +0100 Subject: [PATCH 0216/1444] New translations satoshis-ridge.md (German) --- .../current/tutorials/satoshis-ridge.md | 75 +++++++++++++++++++ 1 file changed, 75 insertions(+) create mode 100644 i18n/de/docusaurus-plugin-content-docs/current/tutorials/satoshis-ridge.md diff --git a/i18n/de/docusaurus-plugin-content-docs/current/tutorials/satoshis-ridge.md b/i18n/de/docusaurus-plugin-content-docs/current/tutorials/satoshis-ridge.md new file mode 100644 index 0000000000..596339ae74 --- /dev/null +++ b/i18n/de/docusaurus-plugin-content-docs/current/tutorials/satoshis-ridge.md @@ -0,0 +1,75 @@ +--- +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 arguable one of its strengths. + +Instead, we need to create separate layers that add additional functionality without modify 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. From 78993aa41acbfde10ee71b91fc5994b8ca688b70 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:40:35 +0100 Subject: [PATCH 0217/1444] New translations crash-course.md (German) --- .../current/clarity/crash-course.md | 122 ++++++++++++++++++ 1 file changed, 122 insertions(+) create mode 100644 i18n/de/docusaurus-plugin-content-docs/current/clarity/crash-course.md diff --git a/i18n/de/docusaurus-plugin-content-docs/current/clarity/crash-course.md b/i18n/de/docusaurus-plugin-content-docs/current/clarity/crash-course.md new file mode 100644 index 0000000000..5b27a3c275 --- /dev/null +++ b/i18n/de/docusaurus-plugin-content-docs/current/clarity/crash-course.md @@ -0,0 +1,122 @@ +--- +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.md). + +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. + +```clojure +(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: + +```clojure +(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. From ac7e9ea4a5e7fab903a7b88f79dc2a52b412b793 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:40:35 +0100 Subject: [PATCH 0218/1444] New translations sample-contracts.md (German) --- .../current/clarity/sample-contracts.md | 14 ++++++++++++++ 1 file changed, 14 insertions(+) create mode 100644 i18n/de/docusaurus-plugin-content-docs/current/clarity/sample-contracts.md diff --git a/i18n/de/docusaurus-plugin-content-docs/current/clarity/sample-contracts.md b/i18n/de/docusaurus-plugin-content-docs/current/clarity/sample-contracts.md new file mode 100644 index 0000000000..adb12a58fd --- /dev/null +++ b/i18n/de/docusaurus-plugin-content-docs/current/clarity/sample-contracts.md @@ -0,0 +1,14 @@ +--- +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) From ce689b7c795ff00d3937c854a7bd9cafc38a7d93 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:40:36 +0100 Subject: [PATCH 0219/1444] New translations index.md (German) --- .../current/cookbook/index.md | 64 +++++++++++++++++++ 1 file changed, 64 insertions(+) create mode 100644 i18n/de/docusaurus-plugin-content-docs/current/cookbook/index.md diff --git a/i18n/de/docusaurus-plugin-content-docs/current/cookbook/index.md b/i18n/de/docusaurus-plugin-content-docs/current/cookbook/index.md new file mode 100644 index 0000000000..a2b0e42eea --- /dev/null +++ b/i18n/de/docusaurus-plugin-content-docs/current/cookbook/index.md @@ -0,0 +1,64 @@ +--- +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 + +Swapping between Bitcoin and Stacks addresses + +Swapping between xBTC and BTC + +Verifying a transaction on the BTC chain + +## 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 + +Airdropping an NFT to a Bitcoin address + +## Stacking and Mining + +Simple stacking pool + +Continuous stacking + +Simple mining pool + +Proof of PoX payout + +## Oracles + +Creating a simple BTC price oracle + +## Frontend + +[Post conditions with Stacks.js](./post-conditions) + +[Authentication with Stacks.js](./stacks-js-auth) + +[Sending transactions with Stacks.js](./stacks-js-sending-transactions) + +## Complete Apps + +[Sup](https://github.com/kenrogers/sup) + +[Hello Stacks](https://github.com/kenrogers/hello-stacks) From 787dbfb0851cb3309826031d9ecc22d62ba80f8f Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:40:37 +0100 Subject: [PATCH 0220/1444] New translations btc-connection.md (German) --- .../current/stacks-academy/btc-connection.md | 196 ++++++++++++++++++ 1 file changed, 196 insertions(+) create mode 100644 i18n/de/docusaurus-plugin-content-docs/current/stacks-academy/btc-connection.md diff --git a/i18n/de/docusaurus-plugin-content-docs/current/stacks-academy/btc-connection.md b/i18n/de/docusaurus-plugin-content-docs/current/stacks-academy/btc-connection.md new file mode 100644 index 0000000000..b4db915969 --- /dev/null +++ b/i18n/de/docusaurus-plugin-content-docs/current/stacks-academy/btc-connection.md @@ -0,0 +1,196 @@ +--- +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. + +## Stacks Among Other Bitcoin Layers + +In the [last section](./what-is-stacks.md) we covered what Stacks actually is and what problem it is solving, but this is not a new problem. The Bitcoin write problem has been a bit of a holy grail problem in the crypto world for a while now. + +Bitcoin is the OG cryptocurrency and has the largest market cap, but it also some of the least functionality, which means if we want to make it a productive asset and use it to build a decentralized economy, we need to take a layered approach and let Bitcoin do what it does best, while creating additional layers on top of it to add functionality. + +So how does Stacks compare to some of the other approaches to layering on top of Bitcoin? + +### 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. + +## 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. + +But because it has its own execution environment and smart contract state to maintain, it needs a token to incentivize maintenance of the network. + +But it goes further than that. It is possible to build a system like this without a token using something like merge-mining or a sidechain, but then we lose out on the additional benefit of having the chain state's safety underpinned by its entire token economy's value. + +In the case of Stacks, the safety and liveness of the chain are underpinned by this value, and the stacking mechanism incentivizes network members to increase this value. + +From Jude Nelson, Stacks core developer: + +"How hard is it to cause a safety failure (i.e. a double-spend via a reorg) on just the canonical Stacks chain fork? Anyone can become a miner by spending BTC, so without loss of generality, reverting the last block on the canonical chain is at least as hard in expectation as spending more BTC than the rest of the miners combined for that block. Because each Bitcoin block selects at most one Stacks block, the act of reorging the canonical Stacks chain back N blocks is the act of winning at least N + 1 blocks built off of a common ancestor that is N blocks deep. This is a lower bound on the number of Bitcoin blocks mined during which a reorg needs to take place — in practice, honest miners will keep working on the canonical chain, and will win some Stacks blocks of their own, which in turn increases the number of Stacks blocks the reorging miners must win. + +How costly is it to carry out a reorg of N blocks? It’s a function of how valuable STX is relative to BTC — the more valuable STX are, the more BTC honest miners are committing to mining (this has borne out in practice), and thus the more BTC a reorging miner must commit. Therefore, the cost of a reorg is a function of the value of STX. + +This is similar to the economic security of a PoW blockchain. Like in PoW, each fork of the Stacks chain has its own independent “security budget” — an attacker must out-spend the security budget to carry out a reorg, and the security budget is a function of the block rewards. In PoX, the only difference is that the miners spend another blockchain’s tokens (BTC in Stacks’ case) instead of energy. Therefore, Stacks can’t be a sidechain, a drivechain, or a merge-mined chain, because none of these other systems’ security budgets are a function of their tokens’ worth. Sidechains, drivechains, and merged-mined chains all rely on external miners for their safety, since their safety is guaranteed in part by external miners validating their blocks. The onus on these systems is to get external miners to care enough to do so, and in the case of sidechains, drivechains, and blind merged-mined chains, there is an additional onus to encourage their nodes to mine blocks at all (since there is no on-chain reward for them to earn by doing so). By contrast, disinterested Bitcoin miners neither assist nor prevent a reorg in PoX — they only record the history of all Stacks forks. + +PoX offers two additional, unique security properties on top of PoW. First, no matter how much BTC a reorging miner can commit, the act of executing a reorg is going to be time-consuming. Unless the attacker can attack the Bitcoin chain itself by quickly producing a better Bitcoin fork, a reorging miner must sustain the attack for at least N + 1 Bitcoin blocks. This gives honest miners and users ample time to notice and react to the reorg attempt. + +Second, the history of block production in all Stacks forks is embedded within Bitcoin. This allows the system to leverage Bitcoin’s security budget in order to ensure that all forks are public. This is because the act of producing a hidden Stacks fork, where the fork’s block hashes are not known to the honest miners, is the act of producing a hidden canonical Bitcoin fork. Therefore, the act of producing a hidden Stacks fork is at least as hard as reorging the Bitcoin chain. A PoX chain leverages this property not to prevent reorgs, but to make reorgs unprofitable. + +By anchoring blocks to an existing blockchain, a PoX chain forces reorgs to happen out in the open, thereby giving advance warning to all honest network participants when they happen. Honest miners, users, and exchanges will see the PoX transactions for reorg attempts on the existing blockchain, and adapt their behaviors accordingly: honest miners will increase their commitments, and users and exchanges will require more confirmations for transactions. This makes the act of carrying out a reorg while also making a profit much more challenging, since malicious reorgs — like selfish mining and double-spending — rely on secrecy to work effectively. Specific to Stacks, miners are additionally required to mine for a “warm-up” period of two blocks, during which they must spend BTC at their target commit levels but will not win any Stacks blocks. So, a high-budget reorg attempt will not only be costly, but will also alert the rest of the network before the damage is done." + +- [What Kind of Blockchain is Stacks?](https://stacks.org/stacks-blockchain) + +## 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) From ad68e1276079046cb38005371d6223ceb8847243 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:40:38 +0100 Subject: [PATCH 0221/1444] New translations post-conditions.md (German) --- .../current/stacks-academy/post-conditions.md | 39 +++++++++++++++++++ 1 file changed, 39 insertions(+) create mode 100644 i18n/de/docusaurus-plugin-content-docs/current/stacks-academy/post-conditions.md diff --git a/i18n/de/docusaurus-plugin-content-docs/current/stacks-academy/post-conditions.md b/i18n/de/docusaurus-plugin-content-docs/current/stacks-academy/post-conditions.md new file mode 100644 index 0000000000..bb0727194f --- /dev/null +++ b/i18n/de/docusaurus-plugin-content-docs/current/stacks-academy/post-conditions.md @@ -0,0 +1,39 @@ +--- +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). From 3d84738c4f3b01d7c2371d259b8cc062775c97b7 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:40:39 +0100 Subject: [PATCH 0222/1444] New translations creating-an-ft.md (German) --- .../current/cookbook/creating-an-ft.md | 99 +++++++++++++++++++ 1 file changed, 99 insertions(+) create mode 100644 i18n/de/docusaurus-plugin-content-docs/current/cookbook/creating-an-ft.md diff --git a/i18n/de/docusaurus-plugin-content-docs/current/cookbook/creating-an-ft.md b/i18n/de/docusaurus-plugin-content-docs/current/cookbook/creating-an-ft.md new file mode 100644 index 0000000000..4e3bad99d2 --- /dev/null +++ b/i18n/de/docusaurus-plugin-content-docs/current/cookbook/creating-an-ft.md @@ -0,0 +1,99 @@ +--- +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) + ) +) +``` From 8e2041f0c880e0a0d393b8e60c8da176c1a2a1e8 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:40:40 +0100 Subject: [PATCH 0223/1444] New translations creating-an-nft.md (German) --- .../current/cookbook/creating-an-nft.md | 87 +++++++++++++++++++ 1 file changed, 87 insertions(+) create mode 100644 i18n/de/docusaurus-plugin-content-docs/current/cookbook/creating-an-nft.md diff --git a/i18n/de/docusaurus-plugin-content-docs/current/cookbook/creating-an-nft.md b/i18n/de/docusaurus-plugin-content-docs/current/cookbook/creating-an-nft.md new file mode 100644 index 0000000000..08faf9393a --- /dev/null +++ b/i18n/de/docusaurus-plugin-content-docs/current/cookbook/creating-an-nft.md @@ -0,0 +1,87 @@ +--- +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 +Code for this recipe has been pulled from [this NFT tutorial](https://blog.developerdao.com/building-an-nft-with-stacks-and-clarity) from Developer DAO. +::: + +## 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) + ) +) +``` From da463f08cca5918d63360b17a4918bfad982977d Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:40:40 +0100 Subject: [PATCH 0224/1444] New translations post-conditions.md (German) --- .../current/cookbook/post-conditions.md | 136 ++++++++++++++++++ 1 file changed, 136 insertions(+) create mode 100644 i18n/de/docusaurus-plugin-content-docs/current/cookbook/post-conditions.md diff --git a/i18n/de/docusaurus-plugin-content-docs/current/cookbook/post-conditions.md b/i18n/de/docusaurus-plugin-content-docs/current/cookbook/post-conditions.md new file mode 100644 index 0000000000..571fc20d48 --- /dev/null +++ b/i18n/de/docusaurus-plugin-content-docs/current/cookbook/post-conditions.md @@ -0,0 +1,136 @@ +--- +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. From 903a4e4f83c12acd0c44e0fec5defc1d520eaf3c Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:40:41 +0100 Subject: [PATCH 0225/1444] New translations stacks-js-auth.md (German) --- .../current/cookbook/stacks-js-auth.md | 98 +++++++++++++++++++ 1 file changed, 98 insertions(+) create mode 100644 i18n/de/docusaurus-plugin-content-docs/current/cookbook/stacks-js-auth.md diff --git a/i18n/de/docusaurus-plugin-content-docs/current/cookbook/stacks-js-auth.md b/i18n/de/docusaurus-plugin-content-docs/current/cookbook/stacks-js-auth.md new file mode 100644 index 0000000000..89d1f06e00 --- /dev/null +++ b/i18n/de/docusaurus-plugin-content-docs/current/cookbook/stacks-js-auth.md @@ -0,0 +1,98 @@ +--- +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 && ( + + ); +} +``` From 642fbf9ddf07aa3dd1e9d817d8d18a8e5337c702 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:40:42 +0100 Subject: [PATCH 0226/1444] New translations stacks-js-sending-transactions.md (German) --- .../stacks-js-sending-transactions.md | 55 +++++++++++++++++++ 1 file changed, 55 insertions(+) create mode 100644 i18n/de/docusaurus-plugin-content-docs/current/cookbook/stacks-js-sending-transactions.md diff --git a/i18n/de/docusaurus-plugin-content-docs/current/cookbook/stacks-js-sending-transactions.md b/i18n/de/docusaurus-plugin-content-docs/current/cookbook/stacks-js-sending-transactions.md new file mode 100644 index 0000000000..849c7d1f42 --- /dev/null +++ b/i18n/de/docusaurus-plugin-content-docs/current/cookbook/stacks-js-sending-transactions.md @@ -0,0 +1,55 @@ +--- +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. From d60fc7f051c3fbe51da35c34781b5b8ff93a11ab Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:40:43 +0100 Subject: [PATCH 0227/1444] New translations _category_.json (German) --- .../current/clarity/noteworthy-contracts/_category_.json | 8 ++++++++ 1 file changed, 8 insertions(+) create mode 100644 i18n/de/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/_category_.json diff --git a/i18n/de/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/_category_.json b/i18n/de/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/_category_.json new file mode 100644 index 0000000000..f5de305558 --- /dev/null +++ b/i18n/de/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/_category_.json @@ -0,0 +1,8 @@ +{ + "label": "Noteworthy Contracts", + "position": 4, + "link": { + "type": "generated-index", + "description": "Specific deployed Clarity Contracts worth mentioning." + } +} \ No newline at end of file From ee6a1b70ac62a684122f0d6af06e24af223b26a3 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:40:44 +0100 Subject: [PATCH 0228/1444] New translations bns-contract.md (German) --- .../noteworthy-contracts/bns-contract.md | 519 ++++++++++++++++++ 1 file changed, 519 insertions(+) create mode 100644 i18n/de/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/bns-contract.md diff --git a/i18n/de/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/bns-contract.md b/i18n/de/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/bns-contract.md new file mode 100644 index 0000000000..a7770b7d24 --- /dev/null +++ b/i18n/de/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/bns-contract.md @@ -0,0 +1,519 @@ +--- +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 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` From 3eea0e675952e1e9d9667ef6b821b6966b32314c Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:40:45 +0100 Subject: [PATCH 0229/1444] New translations xbtc.md (German) --- .../clarity/noteworthy-contracts/xbtc.md | 28 +++++++++++++++++++ 1 file changed, 28 insertions(+) create mode 100644 i18n/de/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/xbtc.md diff --git a/i18n/de/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/xbtc.md b/i18n/de/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/xbtc.md new file mode 100644 index 0000000000..e535dcf260 --- /dev/null +++ b/i18n/de/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/xbtc.md @@ -0,0 +1,28 @@ +--- +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) From 4e134fcb0f32548e5b2ced49e00dfd649bcbcc4d Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:40:46 +0100 Subject: [PATCH 0230/1444] New translations index.md (German) --- .../current/glossary/index.md | 284 ++++++++++++++++++ 1 file changed, 284 insertions(+) create mode 100644 i18n/de/docusaurus-plugin-content-docs/current/glossary/index.md diff --git a/i18n/de/docusaurus-plugin-content-docs/current/glossary/index.md b/i18n/de/docusaurus-plugin-content-docs/current/glossary/index.md new file mode 100644 index 0000000000..419c0e0d73 --- /dev/null +++ b/i18n/de/docusaurus-plugin-content-docs/current/glossary/index.md @@ -0,0 +1,284 @@ +--- +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. From 744553f2dde2c247b76370c1ae4c984b27701cea Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:40:46 +0100 Subject: [PATCH 0231/1444] New translations quicknode.md (German) --- .../current/nodes-and-miners/quicknode.md | 45 +++++++++++++++++++ 1 file changed, 45 insertions(+) create mode 100644 i18n/de/docusaurus-plugin-content-docs/current/nodes-and-miners/quicknode.md diff --git a/i18n/de/docusaurus-plugin-content-docs/current/nodes-and-miners/quicknode.md b/i18n/de/docusaurus-plugin-content-docs/current/nodes-and-miners/quicknode.md new file mode 100644 index 0000000000..1281964689 --- /dev/null +++ b/i18n/de/docusaurus-plugin-content-docs/current/nodes-and-miners/quicknode.md @@ -0,0 +1,45 @@ +--- +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. From f4cf6783e05cdf86985a9a7a5341d8474114108a Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:40:47 +0100 Subject: [PATCH 0232/1444] New translations defi.md (German) --- .../current/services-using-stacks/defi.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) 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 index 51defacba7..58717a3234 100644 --- 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 @@ -26,7 +26,7 @@ Please edit this page to add any relevant new site that we are missing. ## Lnswap -[LNSWAP](https://www.lnswap.org). Non custiodial crypto currency exchange +[LNSWAP](https://www.lnswap.org). Non-custodial crypto currency exchange ![](/img/sh_lnswap.png) @@ -41,4 +41,3 @@ Please edit this page to add any relevant new site that we are missing. [Stackswap](https://app.stackswap.org/v2) ![](/img/sh_stackswap.png) - From f4f333c620c950a98b468c9f4df7d1846160553f Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:40:48 +0100 Subject: [PATCH 0233/1444] New translations more.md (German) --- .../current/services-using-stacks/more.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) 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 index df0b3e2254..1e14b9a5a5 100644 --- 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 @@ -18,6 +18,6 @@ Please edit this page to add any relevant new site that we are missing. ## Sigle -[Sigle](https://www.sigle.io/) is a decentralised and open source web 3 writing platform. +[Sigle](https://www.sigle.io/) is a decentralized and open source web 3 writing platform. -![](/img/sh_sigle.png) \ No newline at end of file +![](/img/sh_sigle.png) From 5e6c91dff409afa777c7ffe0c0dc4ff81b2167c9 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:40:49 +0100 Subject: [PATCH 0234/1444] New translations nft.md (German) --- .../current/services-using-stacks/nft.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) 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 index abb770663c..d582604854 100644 --- 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 @@ -15,6 +15,7 @@ Please edit this page to add any relevant new site that we are missing. ![website-screenshot](/img/sh_nft_byzantion.png) ### [Gamma](https://gamma.io/) + ![website-screenshot](/img/sh_nft_gamma.png) ### [Megapont](https://www.megapont.com/) @@ -35,4 +36,4 @@ Please edit this page to add any relevant new site that we are missing. ### [Superfandom](https://superfandom.io/) -![website-screenshot](/img/sh_superfandom.png) \ No newline at end of file +![website-screenshot](/img/sh_superfandom.png) From afa3fd8a3795d6c5a73aef77a76c8391318c81aa Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:40:50 +0100 Subject: [PATCH 0235/1444] New translations stacks-info-sites.md (German) --- .../current/services-using-stacks/stacks-info-sites.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) 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 index 35ced8dac6..54f6823e33 100644 --- 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 @@ -30,7 +30,7 @@ Please edit this page to add any relevant new site that we are missing. ![website-screenshot](/img/sh_stxstats.png) -### [Novuminsights](https://stacks.novuminsights.com/health) +### [Novum Insights](https://stacks.novuminsights.com/health) ![website-screenshot](/img/sh_novuminsights.png) From 86f4dd51fcbc9792bbf047f8620108f4501b0eee Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:40:51 +0100 Subject: [PATCH 0236/1444] New translations wallets.md (German) --- .../current/services-using-stacks/wallets.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) 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 index e5ea6c5b45..2d3fcc85f2 100644 --- 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 @@ -15,6 +15,7 @@ Please edit this page to add any relevant new site that we are missing. [Blockchain.com](https://www.blockchain.com/wallet) ![](/img/sh_blockchain.png) + ## Boom [Boom](https://boom.money) @@ -26,6 +27,7 @@ Please edit this page to add any relevant new site that we are missing. [D'CENT](https://dcentwallet.com) ![](/img/sh_dcent.png) + ## Hiro Wallet [Hiro Wallet](https://www.hiro.so/wallet) @@ -48,4 +50,4 @@ Please edit this page to add any relevant new site that we are missing. [Wise](https://wiseapp.id) -![](/img/sh_wiseapp.png) \ No newline at end of file +![](/img/sh_wiseapp.png) From 042d401364a7e85c3885c3b3e0723e8897dda1af Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:40:52 +0100 Subject: [PATCH 0237/1444] New translations whitepapers.md (German) --- .../current/stacks-academy/whitepapers.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) create mode 100644 i18n/de/docusaurus-plugin-content-docs/current/stacks-academy/whitepapers.md diff --git a/i18n/de/docusaurus-plugin-content-docs/current/stacks-academy/whitepapers.md b/i18n/de/docusaurus-plugin-content-docs/current/stacks-academy/whitepapers.md new file mode 100644 index 0000000000..0e564fbf44 --- /dev/null +++ b/i18n/de/docusaurus-plugin-content-docs/current/stacks-academy/whitepapers.md @@ -0,0 +1,12 @@ +--- +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) From 466042ac3321e40e9a9d2d06941ffc757e0bdd9e Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:40:52 +0100 Subject: [PATCH 0238/1444] New translations stacking-contract.md (German) --- .../noteworthy-contracts/stacking-contract.md | 352 ++++++++++++++++++ 1 file changed, 352 insertions(+) create mode 100644 i18n/de/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/stacking-contract.md diff --git a/i18n/de/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/stacking-contract.md b/i18n/de/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/stacking-contract.md new file mode 100644 index 0000000000..c0027256cd --- /dev/null +++ b/i18n/de/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/stacking-contract.md @@ -0,0 +1,352 @@ +--- +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. 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` From cc3eddd8aa9a5665a4fbd84528beb08d022fa0f3 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:40:53 +0100 Subject: [PATCH 0239/1444] New translations index.md (German) --- .../current/next-steps/index.md | 39 +++++++++++++++++++ 1 file changed, 39 insertions(+) create mode 100644 i18n/de/docusaurus-plugin-content-docs/current/next-steps/index.md diff --git a/i18n/de/docusaurus-plugin-content-docs/current/next-steps/index.md b/i18n/de/docusaurus-plugin-content-docs/current/next-steps/index.md new file mode 100644 index 0000000000..00ddec9178 --- /dev/null +++ b/i18n/de/docusaurus-plugin-content-docs/current/next-steps/index.md @@ -0,0 +1,39 @@ +--- +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) From 3a8f00f0e667e3a3fafc2f27a86f83538da213ca Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:40:54 +0100 Subject: [PATCH 0240/1444] New translations sips.md (German) --- .../current/stacks-academy/sips.md | 52 +++++++++++++++++++ 1 file changed, 52 insertions(+) create mode 100644 i18n/de/docusaurus-plugin-content-docs/current/stacks-academy/sips.md diff --git a/i18n/de/docusaurus-plugin-content-docs/current/stacks-academy/sips.md b/i18n/de/docusaurus-plugin-content-docs/current/stacks-academy/sips.md new file mode 100644 index 0000000000..aa2db18e62 --- /dev/null +++ b/i18n/de/docusaurus-plugin-content-docs/current/stacks-academy/sips.md @@ -0,0 +1,52 @@ +--- +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/IJ15791776) 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-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. From 82f62025cd79a9ddd19719bef187e7fb65e1527b Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:40:55 +0100 Subject: [PATCH 0241/1444] New translations hosted-nodes.md (German) --- .../current/nodes-and-miners/hosted-nodes.md | 25 +++++++++++++++++++ 1 file changed, 25 insertions(+) create mode 100644 i18n/de/docusaurus-plugin-content-docs/current/nodes-and-miners/hosted-nodes.md diff --git a/i18n/de/docusaurus-plugin-content-docs/current/nodes-and-miners/hosted-nodes.md b/i18n/de/docusaurus-plugin-content-docs/current/nodes-and-miners/hosted-nodes.md new file mode 100644 index 0000000000..12d86c7ee2 --- /dev/null +++ b/i18n/de/docusaurus-plugin-content-docs/current/nodes-and-miners/hosted-nodes.md @@ -0,0 +1,25 @@ +--- +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. From ed98d8bc48a4d9ed59aa49b1d3525c32ff109a15 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:40:56 +0100 Subject: [PATCH 0242/1444] New translations authentication.md (Japanese) --- .../current/stacks-academy/authentication.md | 63 +++++++++++++++++++ 1 file changed, 63 insertions(+) create mode 100644 i18n/ja/docusaurus-plugin-content-docs/current/stacks-academy/authentication.md diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/stacks-academy/authentication.md b/i18n/ja/docusaurus-plugin-content-docs/current/stacks-academy/authentication.md new file mode 100644 index 0000000000..8152a401f9 --- /dev/null +++ b/i18n/ja/docusaurus-plugin-content-docs/current/stacks-academy/authentication.md @@ -0,0 +1,63 @@ +--- +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/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. From 87b0d4449b43607c3452a8dd6158ba38629720d3 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:40:57 +0100 Subject: [PATCH 0243/1444] New translations bns.md (Japanese) --- .../current/stacks-academy/bns.md | 242 ++++++++++++++++++ 1 file changed, 242 insertions(+) create mode 100644 i18n/ja/docusaurus-plugin-content-docs/current/stacks-academy/bns.md diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/stacks-academy/bns.md b/i18n/ja/docusaurus-plugin-content-docs/current/stacks-academy/bns.md new file mode 100644 index 0000000000..4c89d9e56c --- /dev/null +++ b/i18n/ja/docusaurus-plugin-content-docs/current/stacks-academy/bns.md @@ -0,0 +1,242 @@ +--- +title: Blockchain Naming System +description: Binds Stacks usernames to off-chain state +sidebar_position: 8 +--- + +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 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). From 64f3cf2eab0796ae7b5afa1ce83edac165cd8c18 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:40:58 +0100 Subject: [PATCH 0244/1444] New translations docs.md (Japanese) --- .../current/contribute/docs.md | 24 ++++++++++++------- 1 file changed, 15 insertions(+), 9 deletions(-) diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/contribute/docs.md b/i18n/ja/docusaurus-plugin-content-docs/current/contribute/docs.md index 77705451b8..b2fef628f9 100644 --- a/i18n/ja/docusaurus-plugin-content-docs/current/contribute/docs.md +++ b/i18n/ja/docusaurus-plugin-content-docs/current/contribute/docs.md @@ -7,7 +7,7 @@ description: Learn how this site is built, and how you can contribute to it. 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). +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/). @@ -15,7 +15,7 @@ Don't want to learn it? No need to. Write [in plain text an issue on Github](htt :::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 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). @@ -24,28 +24,32 @@ To add new content, they are two different ways to do it, the [easy way](#easy-w [**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. +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 yourhanges in real time. + - `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. -## Aditional information +## 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 ``` @@ -54,8 +58,8 @@ Before running this command for the first time you will need to run `npm install 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 ``` @@ -91,7 +95,7 @@ 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. +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 @@ -124,6 +128,7 @@ And execute prettier with the following command: npx prettier --write mynewfiletocheck.md ``` --> + ### 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. @@ -138,6 +143,7 @@ To write a code block, you need to wrap your code in ` ```language `, and end yo (define-public (get-counter) (ok (var-get counter))) ``` + ### Admonitions You can use the following admonitions to highlight content. @@ -204,4 +210,4 @@ Some **content** with _markdown_ `syntax`. Some **content** with _markdown_ `syntax`. -::: \ No newline at end of file +::: From 65c6d86b2efe1bc2fc3b343d0db6f5faec6743bf Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:41:00 +0100 Subject: [PATCH 0245/1444] New translations translations.md (Japanese) --- .../current/contribute/translations.md | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/contribute/translations.md b/i18n/ja/docusaurus-plugin-content-docs/current/contribute/translations.md index bd9a452333..fe8f8c6027 100644 --- a/i18n/ja/docusaurus-plugin-content-docs/current/contribute/translations.md +++ b/i18n/ja/docusaurus-plugin-content-docs/current/contribute/translations.md @@ -1,25 +1,24 @@ --- title: Contribute with translations -description: Want to help tranlating these docs to your local language? +description: Want to help translating 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. +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 Crodin intead. +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 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 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) From 478ad23a0e5bf400287a6d01726d41e5e1a77384 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:41:02 +0100 Subject: [PATCH 0246/1444] New translations gaia-on-ec2.md (Japanese) --- .../current/gaia/gaia-on-ec2.md | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) 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 index 2067e7d57c..3f58ca5e68 100644 --- 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 @@ -26,9 +26,10 @@ Use a link in the table to launch the [CloudFormation](https://console.aws.amazo ### Step 2 - Setup stack using template -You need to configure the template with the appropiate values for your hub and domain it runs on. +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 ``` @@ -52,7 +53,7 @@ Specify the stack details and then click `Next`: ![Specify template](/img/cloudf | 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`. | +| 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 | @@ -93,7 +94,9 @@ ssh -i admin@ 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 +![](/img/cloudformation-gaia-template1-designer.png) From cd4a6d0ea8a53f6d9d45a8d4d3c4ed27ddb032fc Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:41:03 +0100 Subject: [PATCH 0247/1444] New translations gaia.md (Japanese) --- .../current/gaia/gaia.md | 12 +++++++++--- 1 file changed, 9 insertions(+), 3 deletions(-) diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/gaia/gaia.md b/i18n/ja/docusaurus-plugin-content-docs/current/gaia/gaia.md index 1070857350..f86a0d61dc 100644 --- a/i18n/ja/docusaurus-plugin-content-docs/current/gaia/gaia.md +++ b/i18n/ja/docusaurus-plugin-content-docs/current/gaia/gaia.md @@ -1,14 +1,20 @@ --- title: Gaia description: Decentralized storage architecture for off-chain data -sidebar_position: 5 +sidebar_position: 6 tags: - gaia --- ## Introduction -Apps built with the Stacks blockchain store off-chain data using a storage system called Gaia. +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. @@ -38,7 +44,7 @@ The Stacks blockchain stores only identity data. Data created by the actions of 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) +![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. From c964aab2ad9b3fd8f603616bc9152abc58f23a38 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:41:04 +0100 Subject: [PATCH 0248/1444] New translations setup-linux.md (Japanese) --- .../current/gaia/setup-linux.md | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) 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 index db427f890a..2c0ca2b92e 100644 --- a/i18n/ja/docusaurus-plugin-content-docs/current/gaia/setup-linux.md +++ b/i18n/ja/docusaurus-plugin-content-docs/current/gaia/setup-linux.md @@ -1,6 +1,6 @@ --- 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. +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 @@ -19,8 +19,7 @@ This configuration will setup the following 4 docker containers: 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: +**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 @@ -48,8 +47,7 @@ chmod +x ${DESTINATION_DC}/docker-compose 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. +**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 From 4e831c2d23c7be9baeae005239d6ac48a90f282c Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:41:05 +0100 Subject: [PATCH 0249/1444] New translations digitalocean.md (Japanese) --- .../current/nodes-and-miners/digitalocean.md | 41 +++++++++++-------- 1 file changed, 25 insertions(+), 16 deletions(-) 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 index dd7194f504..15df918d04 100644 --- 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 @@ -1,28 +1,30 @@ --- -title: Stacks on DigitalOcean +title: Run a Node with Digital Ocean description: A guide to setup Stacks on DigitalOcean -sidebar_position: 4 +sidebar_position: 2 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). +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`. +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 plan that meets the minimum requirements) and your prefered datacenter region. ![](/img/sh_digitalocean-choose-plan.png) +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 if your prefer. +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) @@ -46,41 +48,48 @@ Congratulations! You are now running the Stacks Blockchain. You can click on `Co ## 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). +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`. -Once the stacks blockchain starts to sync with peers, application ports will open and nginx port 80 will now start proxying requests. +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 v3.0.3 (master:cd0c8aef)", + "server_version": "stacks-blockchain-api v6.2.3 (master:77ab3ae2)", "status": "ready", "chain_tip": { - "block_height": 16220, - "block_hash": "0x3123fba9c0de6b569573494cf83c1d5d198a66bfd5f48ef97949b6bf11ba13be", - "index_block_hash": "0xeec960fbbd6186b4ccac85ce12adba72be497d881f81e077305c90955b51a6ae" + "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/README.md#quickstart). +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). -## API Creation +## 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 -curl -X POST -H 'Content-Type: application/json' \ +$ export TOKEN= +$ 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"}' \ + '{"name":"stacks-blockchain","region":"sfo2","size":"s-2vcpu-4gb","image":"stacksfoundation-stacksblockchain"}' \ "https://api.digitalocean.com/v2/droplets" ``` From deda2b0b0c67f1518547df3c74a84237ed7189eb Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:41:06 +0100 Subject: [PATCH 0250/1444] New translations index.md (Japanese) --- .../current/nodes-and-miners/index.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) 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 index b6cbb9754a..e5f4f2c250 100644 --- 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 @@ -1,11 +1,11 @@ --- title: Nodes and Miners description: Nodes and Miners -sidebar_position: 7 +sidebar_position: 5 --- -Here are all the steps to run nodes and miners, both on mainnet and testnet. +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. -## What's a Stacks node? +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. -## What's a Stacks miner? +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. From 9be404285693e6622757a35f10b8f2c10061f099 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:41:07 +0100 Subject: [PATCH 0251/1444] New translations miner-mainnet.md (Japanese) --- .../current/nodes-and-miners/miner-mainnet.md | 301 +++++++----------- 1 file changed, 110 insertions(+), 191 deletions(-) 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 index 061f4a2511..5afd34c23f 100644 --- 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 @@ -1,166 +1,100 @@ --- title: Mine mainnet Stacks tokens -description: Set up and run a miner on the Stacks 2.0 mainnet -sidebar_position: 5 +description: Set up and run a miner on Stacks Mainnet +sidebar_position: 6 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. +For more on the technical details of mining, please review the [mining guide](../stacks-academy/mining) -If you're interested in mining on the testnet, you can find instructions on how to do that [here](miner-testnet): +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 want to learn more about the technical details of mining, please review the [mining guide](../understand-stacks/mining): +If you're interested in mining on the Stacks testnet, you can find instructions on how to do that [here](miner-testnet): -## Running bitcoind locally +## Running a Bitcoin Mainnet Full Node -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) +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. -First, download the bitcoind software for your platform from https://bitcoin.org/en/download. +- [Ensure your computer meets the minimum hardware requirements before continuing.](https://bitcoin.org/en/bitcoin-core/features/requirements#system-requirements) -Next, start bitcoind with the following configuration: +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): -```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 -``` +:::tip It is recommened to use a persistent location for the chainstate, in the steps below we're using `/bitcoin` ::: -Finally, start bitcoind as follows: +### Update the Bitcoin Configuration File -```bash -bitcoind -conf=path/to/bitcoin.conf -``` - -It may take a few days for the node to synchronize with the Bitcoin mainnet. +Next, update the bitcoin configuration: -## 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: +- **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 -[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 = "" -... +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 ``` -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. +### Start Bitcoin -To run your miner, run this in the command line: +Finally, start bitcoin as follows (adjust the `conf` path to where it was created in the previous step, i.e. `$HOME/bitcoin.conf`): ```bash -stacks-node start --config=./testnet/stacks-node/conf/mainnet-miner-conf.toml +bitcoind -conf=$HOME/bitcoin.conf ``` -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 -``` +:::note +It will take a few days for the node to synchronize with Bitcoin mainnet. +::: -The above code will compile an optimized binary. To use it, run: +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 -cd ../.. -./target/release/stacks-node start --config=./mainnet-miner-conf.toml +$ bitcoin-cli \ + -rpcconnect=localhost \ + -rpcport=8332 \ + -rpcuser=btcuser \ + -rpcpassword=btcpassword \ +getblockchaininfo | jq .blocks +773281 ``` -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 Stacks Blockchain miner -## Running a miner in Windows +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) -### Prerequisites +_There may be some extra requirements to building, [defined here](https://github.com/stacksfoundation/miner-docs/blob/main/prerequisites.md#install-required-packages)_ -Make sure are [running a node](run-a-node) and [running bitcoind locally](#running-bitcoind-locally) before starting this tutorial. +:::tip It is recommened to use a persistent location for the chainstate, in the steps below we're using `/stacks-blockchain` ::: -### Generate keychain and get mainnet tokens in Windows +### Generate a keychain -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 cryptocurrency 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: +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 -npm install --global @stacks/cli -stx make_keychain > cli_keychain.json -type cli_keychain.json +npx @stacks/cli make_keychain 2>/dev/null | jq -r ``` -After this runs, you'll probably see some installation logs, and at the end you should see some JSON that looks like this: +After this runs, you should see some JSON printed to the screen that looks like this: ```json { @@ -174,109 +108,99 @@ After this runs, you'll probably see some installation logs, and at the end you } ``` -:::tip Check out the [Stacks CLI reference](https://docs.hiro.so/references/stacks-cli) for more details ::: +:::warning **Do not lose this information** - we'll need to use the `privateKey` and `btcAddress` fields in later steps. ::: -The above BTC address will then need to be imported into the BTC network. +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=your-user -rpcpassword=your-password importaddress +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 configuration file + + +### Update the Stacks Blockchain 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). +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`. -Update the following properties: +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] -... -# Enter your private key here -seed = "replace-with-your-private-key" -local_peer_seed = "replace-with-your-private-key" -... +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] -... -# To mine on mainnet, you need to run bitcoind locally -# Details can be found in above section, 'Running bitcoind locally' +chain = "bitcoin" +mode = "mainnet" peer_host = "127.0.0.1" -username = "" -password = "" -... +username = "" +password = "" +rpc_port = 8332 +peer_port = 8333 +satoshis_per_byte = 100 +burn_fee_cap = 20000 ``` -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 +### Start the Stacks Blockchain -To start your miner, run this in the command line: +To run your miner, run this in the command line: ```bash -stacks-node start --config=testnet/stacks-node/conf/mainnet-miner-conf.toml +stacks-node start --config=$HOME/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 +### 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 -set RUST_BACKTRACE=full; -set STACKS_LOG_DEBUG=1; -stacks-node start --config=mainnet-miner-conf.toml +STACKS_LOG_DEBUG=1 stacks-node start --config=$HOME/mainnet-miner-conf.toml ``` -## Optional: Running with Docker +--- + +## Optional: Running a Stacks Blockchain miner with Docker -Alternatively, you can run the mainnet node with Docker. +Alternatively, you can run a Stacks mainnet miner with Docker. -:::caution Ensure you have [Docker](https://docs.docker.com/get-docker/) installed on your machine. ::: +:::caution Ensure you have [Docker](https://docs.docker.com/get-docker/) installed. ::: -### Generate keychain and get tokens +### 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 +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 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: +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). -```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 = "" -... -``` +### Update Stacks Blockchain Docker Configuration File -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. +Use the steps oulined above to create the [configuration file](miner-mainnet#update-the-stacks-blockchain-configuration-file) -### Start the miner +### 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 ::: @@ -287,7 +211,8 @@ docker run -d \ --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" \ + -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 \ @@ -302,9 +227,9 @@ 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). +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 on your machine: +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) @@ -313,13 +238,7 @@ Ensure you have the following prerequisites installed on your machine: ### 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). +Use the steps [outlined above](miner-mainnet#generate-a-keychain-and-get-some-tokens) ### Install the chart and run the miner From 8f36c69aa7bb8fab5ba8ae3cc666103467c2e105 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:41:08 +0100 Subject: [PATCH 0252/1444] New translations miner-testnet.md (Japanese) --- .../current/nodes-and-miners/miner-testnet.md | 318 +++++++----------- 1 file changed, 130 insertions(+), 188 deletions(-) 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 index 56374190c1..c0a27e63d5 100644 --- 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 @@ -1,35 +1,52 @@ --- title: Mine testnet Stacks tokens -description: Set up and run a miner on the Stacks 2.0 testnet -sidebar_position: 4 +description: Set up and run a miner on Stacks Testnet +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 testnet. +For more on the technical details of mining, please review the [mining guide](../stacks-academy/mining) -If you want to learn more about the technical details of mining, please review the [mining guide](../understand-stacks/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)). -## Running bitcoind locally +If you're interested in mining on the Stacks mainnet, you can find instructions on how to do that [here](miner-mainnet): -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) +## Running a Bitcoin Testnet Full Node -First, download the bitcoind software for your platform from https://bitcoin.org/en/download. +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. -Next, start bitcoind with the following configuration: +- [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 -rpcuser=your-bitcoind-username -rpcpassword=your-bitcoind-password testnet=1 -txindex=0 -listen=1 -rpcserialversion=0 -maxorphantx=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 @@ -37,126 +54,51 @@ 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" -... +### Start Bitcoin -[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: +Finally, start bitcoind as follows: ```bash -stacks-node start --config=./testnet/stacks-node/conf/testnet-miner-conf.toml +bitcoind -conf=$HOME/bitcoin.conf ``` -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 -``` +:::note +It will take a few hours for the node to synchronize with Bitcoin testnet. +::: -The above code will compile an optimized binary. To use it, run: +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 -cd ../.. -./target/release/stacks-node start --config=./testnet/conf/testnet-follower-conf.toml +$ bitcoin-cli \ + -rpcconnect=localhost \ + -rpcport=18332 \ + -rpcuser=btcuser \ + -rpcpassword=btcpass \ +getblockchaininfo | jq .blocks +2417570 ``` -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 +## Running a Stacks Blockchain miner -### Prerequisites +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) -Make sure are [running a testnet node](run-a-node) before starting this tutorial. +_There may be some extra requirements to building, [defined here](https://github.com/stacksfoundation/miner-docs/blob/main/prerequisites.md#install-required-packages)_ -### Generate keychain and get testnet tokens in Windows +:::tip It is recommened to use a persistent location for the chainstate, in the steps below we're using `/stacks-blockchain` ::: -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. +### Generate a keychain -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. +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. -Generate a keychain: +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 -npm install --global @stacks/cli -stx make_keychain -t > cli_keychain.json -type cli_keychain.json +npx @stacks/cli make_keychain -t 2>/dev/null | jq -r ``` -After this runs, you'll probably see some installation logs, and at the end you should see some JSON that looks like this: +After this runs, you should see some JSON printed to the screen that looks like this: ```json { @@ -170,107 +112,110 @@ After this runs, you'll probably see some installation logs, and at the end you } ``` -:::tip Check out the [Stacks CLI reference](https://docs.hiro.so/references/stacks-cli) for more details ::: +:::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. -Request BTC from faucet: +### Update the Stacks Blockchain Configuration File -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/). +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`. -### Update configuration file +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. -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). +Next, update the bitcoin configuration: -Update the following properties: +- **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] -... -seed = "replace-with-your-private-key" -local_peer_seed = "replace-with-your-private-key" -... +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] -... -# To mine on Testnet, you need to run bitcoind locally -# Details can be found in above section, 'Running bitcoind locally' +chain = "bitcoin" +mode = "xenon" peer_host = "127.0.0.1" -username = "" -password = "" -... +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 ``` -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 +### Start the Stacks Blockchain -To start your miner, run this in the command line: +To run your miner, run this in the command line: ```bash -stacks-node start --config=testnet/stacks-node/conf/testnet-miner-conf.toml +stacks-node start --config=$HOME/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 +### 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 -set RUST_BACKTRACE=full; -set STACKS_LOG_DEBUG=1; -stacks-node start --config=testnet-miner-conf.toml +STACKS_LOG_DEBUG=1 stacks-node start --config=$HOME/testnet-miner-conf.toml ``` -## Optional: Running with Docker +--- + +## Optional: Running a Stacks Blockchain miner with Docker -Alternatively, you can run the testnet node with Docker. +Alternatively, you can run a Stacks testnet miner with Docker. -:::warning Ensure you have [Docker](https://docs.docker.com/get-docker/) installed on your machine. ::: +:::caution Ensure you have [Docker](https://docs.docker.com/get-docker/) installed ::: -### Generate keychain and get testnet tokens +### Generate a Keychain and Get Some Tokens Generate a keychain: ```bash -docker run -i node:14-alpine npx @stacks/cli make_keychain -t 2>/dev/null +docker run -i node:14-alpine npx @stacks/cli make_keychain 2>/dev/null | jq -r ``` -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 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. -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 Stacks Blockchain Docker Configuration File -Update the following properties: +Use the steps oulined above to create the [configuration file](miner-testnet#update-the-stacks-blockchain-configuration-file) -```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 +### 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 ::: @@ -281,7 +226,8 @@ docker run -d \ --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" \ + -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 \ @@ -294,26 +240,22 @@ You can review the node logs with this command: 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). +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 on your machine: +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 testnet tokens - -Generate a keychain: - -```bash -docker run -i node:14-alpine npx @stacks/cli make_keychain -t 2>/dev/null -``` +### Generate keychain and get some tokens -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/). +Use the steps [outlined above](miner-testnet#generate-a-keychain-and-get-some-tokens) ### Install the chart and run the miner @@ -324,7 +266,7 @@ 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.node.seed="replace-with-your-privateKey-from-generate-keychain-step" \ ``` You can review the node logs with this command: From 4bb225a93bec30d6e025e810c030aa52ab5ae2cd Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:41:09 +0100 Subject: [PATCH 0253/1444] New translations stacks-node-configuration.md (Japanese) --- .../stacks-node-configuration.md | 158 +++++++++++------- 1 file changed, 101 insertions(+), 57 deletions(-) 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 index 89af343dc6..cd216e7103 100644 --- 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 @@ -1,7 +1,7 @@ --- title: Stacks Node Configuration description: Configuration parameters and options for the stacks-node binary -sidebar_position: 6 +sidebar_position: 4 --- ## Usage @@ -10,97 +10,141 @@ sidebar_position: 6 stacks-node sub-command [--subcommand-option ] ``` -## Subcommands +### 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 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 -### mocknet +## Configuration File Options -Start a node based on a fast local setup emulating a burnchain. Ideal for smart contract development. +The Stacks Blockchain configuration file has multiple sections under which an option may be placed. -Example: +- [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) -```bash -stacks-node mocknet -``` +For reference, several configuration file examples are [available here](https://github.com/stacks-network/stacks-blockchain/tree/master/testnet/stacks-node/conf) -### krypton +- [Example mainnet follower configuration](./stacks-node-configuration#example-mainnet-follower-configuration) -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). +### node -Example: +Contains various configuration options for the stacks-node binary. -```bash -stacks-node krypton -``` +| 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. | -### testnet +### events_observer -Start a node that will join and stream blocks from the public testnet. +:::info This section is _optional_ and not required -Example: +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. -```bash -stacks-node testnet -``` +| 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. | | -### mainnet +### connection_options -Start a node that joins and streams blocks from the public mainnet. +:::info This section is _optional_ and not required. -Example: +However, if this section is added, **all** fields are required ::: -```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. +Specifies configuration options for others connecting to the stacks node. -#### Arguments +| 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 | -**--config**: relative or absolute path to the TOML config file. Required. +### burnchain -Example: +This section contains configuration options pertaining to the blockchain the stacks-node binds to on the backend for proof-of-transfer (BTC). -```bash -stacks-node start --config=/path/to/config.toml -``` +| 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` | -See [Configuration File Options](#configuration-file-options) for more information. +#### Mining -#### version +| 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`. | -Displays information about the current version and the release cycle. +### ustx_balance -Example: +- `mocknet`/`testnet` only -```bash -stacks-node version -``` +This section contains configuration options allocating microSTX per address in the genesis block -#### help +This section can repeat multiple times, but each section can only define a single address. -Displays a help message. +:::info This section is only required for the `testnet` and `mocknet` networks. -Example: +However, if this section is added, **all** fields are required ::: -```bash -stacks-node help -``` +| 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 | -## Configuration File Options +## Example Mainnet Follower Configuration -The TOML configuration file has multiple sections under which an option may be placed. +```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" -To see a list of example configurations, [please see this page](https://github.com/stacks-network/stacks-blockchain/tree/master/testnet/stacks-node/conf). +[burnchain] +chain = "bitcoin" +mode = "mainnet" +peer_host = "localhost" +username = "user" +password = "pass" +rpc_port = 8332 +peer_port = 8333 -### Section: node +[[events_observer]] +endpoint = "localhost:3700" +retry_count = 255 +events_keys = ["*"] +``` -Contains various configuration options pertaining to the stacks-node. -Example: + From 704990723e3d5bcade5b2f2074f3dc60001acd81 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:41:10 +0100 Subject: [PATCH 0254/1444] New translations accounts.md (Japanese) --- .../current/stacks-academy/accounts.md | 215 ++++++++++++++++++ 1 file changed, 215 insertions(+) create mode 100644 i18n/ja/docusaurus-plugin-content-docs/current/stacks-academy/accounts.md diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/stacks-academy/accounts.md b/i18n/ja/docusaurus-plugin-content-docs/current/stacks-academy/accounts.md new file mode 100644 index 0000000000..55d0165def --- /dev/null +++ b/i18n/ja/docusaurus-plugin-content-docs/current/stacks-academy/accounts.md @@ -0,0 +1,215 @@ +--- +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" + } + } + ] +} +``` From 0e8142f7b1006f8c7a1fadc5283c1e37de3ab5c3 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:41:11 +0100 Subject: [PATCH 0255/1444] New translations microblocks.md (Japanese) --- .../current/stacks-academy/microblocks.md | 107 ++++++++++++++++++ 1 file changed, 107 insertions(+) create mode 100644 i18n/ja/docusaurus-plugin-content-docs/current/stacks-academy/microblocks.md diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/stacks-academy/microblocks.md b/i18n/ja/docusaurus-plugin-content-docs/current/stacks-academy/microblocks.md new file mode 100644 index 0000000000..9310aa65be --- /dev/null +++ b/i18n/ja/docusaurus-plugin-content-docs/current/stacks-academy/microblocks.md @@ -0,0 +1,107 @@ +--- +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. + +[provides an endpoint]: https://docs.hiro.so/get-started/stacks-blockchain-api#nonce-handling +[microblocks_api]: https://docs.hiro.so/api#tag/Microblocks From 5ba7babd4c45f1dafda7155f888ab64f2134e3c0 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:41:11 +0100 Subject: [PATCH 0256/1444] New translations mining.md (Japanese) --- .../current/stacks-academy/mining.md | 84 +++++++++++++++++++ 1 file changed, 84 insertions(+) create mode 100644 i18n/ja/docusaurus-plugin-content-docs/current/stacks-academy/mining.md diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/stacks-academy/mining.md b/i18n/ja/docusaurus-plugin-content-docs/current/stacks-academy/mining.md new file mode 100644 index 0000000000..e6e93e130a --- /dev/null +++ b/i18n/ja/docusaurus-plugin-content-docs/current/stacks-academy/mining.md @@ -0,0 +1,84 @@ +--- +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 From dbb48ef7d7e3a50c1608c945891045bec559ead3 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:41:12 +0100 Subject: [PATCH 0257/1444] New translations network.md (Japanese) --- .../current/stacks-academy/network.md | 148 ++++++++++++++++++ 1 file changed, 148 insertions(+) create mode 100644 i18n/ja/docusaurus-plugin-content-docs/current/stacks-academy/network.md diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/stacks-academy/network.md b/i18n/ja/docusaurus-plugin-content-docs/current/stacks-academy/network.md new file mode 100644 index 0000000000..a0dc623d97 --- /dev/null +++ b/i18n/ja/docusaurus-plugin-content-docs/current/stacks-academy/network.md @@ -0,0 +1,148 @@ +--- +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 +} +``` From 0a68fcaa53ef2d30ba2400db220718aefc18ae61 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:41:13 +0100 Subject: [PATCH 0258/1444] New translations stacking.md (Japanese) --- .../current/stacks-academy/stacking.md | 151 ++++++++++++++++++ 1 file changed, 151 insertions(+) create mode 100644 i18n/ja/docusaurus-plugin-content-docs/current/stacks-academy/stacking.md diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/stacks-academy/stacking.md b/i18n/ja/docusaurus-plugin-content-docs/current/stacks-academy/stacking.md new file mode 100644 index 0000000000..545f538ecb --- /dev/null +++ b/i18n/ja/docusaurus-plugin-content-docs/current/stacks-academy/stacking.md @@ -0,0 +1,151 @@ +--- +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. 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. + +![](/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 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 (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 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) From 966de6bf8eecf003fc4eacad679f8d1574ec4aaa Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:41:14 +0100 Subject: [PATCH 0259/1444] New translations technical-specs.md (Japanese) --- .../current/stacks-academy/technical-specs.md | 79 +++++++++++++++++++ 1 file changed, 79 insertions(+) create mode 100644 i18n/ja/docusaurus-plugin-content-docs/current/stacks-academy/technical-specs.md diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/stacks-academy/technical-specs.md b/i18n/ja/docusaurus-plugin-content-docs/current/stacks-academy/technical-specs.md new file mode 100644 index 0000000000..695f849e1a --- /dev/null +++ b/i18n/ja/docusaurus-plugin-content-docs/current/stacks-academy/technical-specs.md @@ -0,0 +1,79 @@ +--- +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). +- 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 whitepaper v2](https://www.youtube.com/watch?v=Wd-Bfe8Sn-Y). From d29abcebbdc2fb18b77dcbc84e8cc65a5ccc999a Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:41:15 +0100 Subject: [PATCH 0260/1444] New translations testnet.md (Japanese) --- .../current/stacks-academy/testnet.md | 35 +++++++++++++++++++ 1 file changed, 35 insertions(+) create mode 100644 i18n/ja/docusaurus-plugin-content-docs/current/stacks-academy/testnet.md diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/stacks-academy/testnet.md b/i18n/ja/docusaurus-plugin-content-docs/current/stacks-academy/testnet.md new file mode 100644 index 0000000000..f8b9f03df2 --- /dev/null +++ b/i18n/ja/docusaurus-plugin-content-docs/current/stacks-academy/testnet.md @@ -0,0 +1,35 @@ +--- +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. + +### 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) From 5aed33742e8322686d62c74c6737720a7bdae6d1 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:41:16 +0100 Subject: [PATCH 0261/1444] New translations transactions.md (Japanese) --- .../current/stacks-academy/transactions.md | 40 +++++++++++++++++++ 1 file changed, 40 insertions(+) create mode 100644 i18n/ja/docusaurus-plugin-content-docs/current/stacks-academy/transactions.md diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/stacks-academy/transactions.md b/i18n/ja/docusaurus-plugin-content-docs/current/stacks-academy/transactions.md new file mode 100644 index 0000000000..ba6b18f0f7 --- /dev/null +++ b/i18n/ja/docusaurus-plugin-content-docs/current/stacks-academy/transactions.md @@ -0,0 +1,40 @@ +--- +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). ::: From 518e9b36a59f2bc0acb76a9ea41a836120605970 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:41:18 +0100 Subject: [PATCH 0262/1444] New translations language-functions.md (Japanese) --- .../current/clarity/language-functions.md | 2031 +++++++++++++++++ 1 file changed, 2031 insertions(+) create mode 100644 i18n/ja/docusaurus-plugin-content-docs/current/clarity/language-functions.md diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/clarity/language-functions.md b/i18n/ja/docusaurus-plugin-content-docs/current/clarity/language-functions.md new file mode 100644 index 0000000000..0325c1ac40 --- /dev/null +++ b/i18n/ja/docusaurus-plugin-content-docs/current/clarity/language-functions.md @@ -0,0 +1,2031 @@ +--- +title: Functions +description: See a detailed list of all functions for the Clarity language. +sidebar_position: 3 +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: + +#### 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-existent\"))))) ;; 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-existent\") ;; 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-existent\" })) ;; 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-existent\" }))) ;; 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-existent\" }))) ;; 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 \"Stacks\" '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 successfully 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_ transferred from another principal, but rather minted. + +If a non-positive amount is provided to mint, this function returns `(err 1)`. Otherwise, on successfully 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_ transferred 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 successfully 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 successfully 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)) +``` From 5562d7b20677944da843ebc995fabe3f9a3d414e Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:41:18 +0100 Subject: [PATCH 0263/1444] New translations language-keywords.md (Japanese) --- .../current/clarity/language-keywords.md | 146 ++++++++++++++++++ 1 file changed, 146 insertions(+) create mode 100644 i18n/ja/docusaurus-plugin-content-docs/current/clarity/language-keywords.md diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/clarity/language-keywords.md b/i18n/ja/docusaurus-plugin-content-docs/current/clarity/language-keywords.md new file mode 100644 index 0000000000..1aca5359c3 --- /dev/null +++ b/i18n/ja/docusaurus-plugin-content-docs/current/clarity/language-keywords.md @@ -0,0 +1,146 @@ +--- +title: Keywords +description: See a detailed list of all keywords for the Clarity language. +sidebar_position: 4 +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 +``` From 8b98873e5ad621d736aae65b6f6f172e89ecce20 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:41:19 +0100 Subject: [PATCH 0264/1444] New translations language-types.md (Japanese) --- .../current/clarity/language-types.md | 25 +++++++++++++++++++ 1 file changed, 25 insertions(+) create mode 100644 i18n/ja/docusaurus-plugin-content-docs/current/clarity/language-types.md diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/clarity/language-types.md b/i18n/ja/docusaurus-plugin-content-docs/current/clarity/language-types.md new file mode 100644 index 0000000000..0af4577dc9 --- /dev/null +++ b/i18n/ja/docusaurus-plugin-content-docs/current/clarity/language-types.md @@ -0,0 +1,25 @@ +--- +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. | From 61c0b552b719420e5f93124a90e1b293a12c3dfe Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:41:21 +0100 Subject: [PATCH 0265/1444] New translations miner-costs-and-fees.md (Japanese) --- .../current/nodes-and-miners/miner-costs-and-fees.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) 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 index 40397a51e0..dd8ee721cc 100644 --- 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 @@ -8,7 +8,7 @@ sidebar_position: 8 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 @@ -22,3 +22,5 @@ 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). From 2310bf469fec82f1401c2dcfe1f14e901e544735 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:41:22 +0100 Subject: [PATCH 0266/1444] New translations verify-miner.md (Japanese) --- .../current/nodes-and-miners/verify-miner.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) 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 index 094e3f03a1..18e8dd3a48 100644 --- 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 @@ -7,7 +7,7 @@ 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 +$ 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 -``` \ No newline at end of file +``` From 793b705187c4fa87b4a6c2b00f34fd007ba5aa9e Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:41:23 +0100 Subject: [PATCH 0267/1444] New translations stacks-blockchain-api.md (Japanese) --- .../stacks-academy/stacks-blockchain-api.md | 41 +++++++++++++++++++ 1 file changed, 41 insertions(+) create mode 100644 i18n/ja/docusaurus-plugin-content-docs/current/stacks-academy/stacks-blockchain-api.md diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/stacks-academy/stacks-blockchain-api.md b/i18n/ja/docusaurus-plugin-content-docs/current/stacks-academy/stacks-blockchain-api.md new file mode 100644 index 0000000000..ad9bb1822e --- /dev/null +++ b/i18n/ja/docusaurus-plugin-content-docs/current/stacks-academy/stacks-blockchain-api.md @@ -0,0 +1,41 @@ +--- +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`. ::: From 981fee0f7a73ad532bd3f43efea9fafce6cff15e Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:41:24 +0100 Subject: [PATCH 0268/1444] New translations run-a-node.md (Japanese) --- .../current/nodes-and-miners/run-a-node.md | 329 +++--------------- 1 file changed, 42 insertions(+), 287 deletions(-) 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 index 94d938c5ca..2993568ce4 100644 --- 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 @@ -1,5 +1,5 @@ --- -title: Run a node +title: Run a Node with Docker description: Set up and run a Stacks node sidebar_position: 1 tags: @@ -8,344 +8,99 @@ tags: ## Stacks Blockchain with Docker -Run your own Stacks Blockchain node easily with just few commands. +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) -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](./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) -## **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 -``` +## **Requirements:** -- With optional proxy: +The **minimum viable requirements** are listed below. -```bash -./manage.sh -n -a start -f proxy -``` +While you _can_ run a node using these specs, it's _recommended_ to assign more than the minimum for better performance. -- With optional bitcoin node: +- ⚠️ [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_ ) -```bash -./manage.sh -n -a start -f bitcoin -``` +:::caution MacOS with an ARM processor is NOT recommended -5. **Stop the Services** +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. ::: -```bash -./manage.sh -n -a stop -``` - -6. **Retrieve Service Logs** - -```bash -./manage.sh -n -a logs -``` - -- Export docker log files to `./exported-logs`: +## **Quickstart** -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. +The `` placeholder used below can be replaced with one of: -```bash -./manage.sh -n -a logs export -``` +- mainnet +- testnet +- mocknet -7. **Restart all services** +1. **Clone the stacks-blockchain-docker repository locally** ```bash -./manage.sh -n -a restart +git clone https://github.com/stacks-network/stacks-blockchain-docker && cd stacks-blockchain-docker ``` -- With optional proxy: +2. **Start the Services** ```bash -./manage.sh -n -a restart -f proxy +./manage.sh -n -a start ``` -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. +:::note With an optional HTTP proxy on port 80: ```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. - +./manage.sh -n -a start -f proxy ``` -9. **Download BNS data to** `./persistent-data/bns-data` - -```bash -./manage.sh bns -``` +::: -10. **Export stacks-blockchain-api events** (_Not applicable for mocknet_) +## **Accessing the services** -```bash -./manage.sh -n -a export -# check logs for completion -./manage.sh -n -a restart -``` +:::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. -11. **Replay stacks-blockchain-api events** (_Not applicable for mocknet_) +Follow the logs to track the sync progress: ```bash -./manage.sh -n -a import -# check logs for completion -./manage.sh -n -a restart +./manage.sh -n -a logs ``` -## **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` +- Ports `20443-20444` are exposed on `localhost` ```bash -curl -sL localhost:20443/v2/info | jq +curl -sL localhost:20443/v2/info | jq -r ``` **stacks-blockchain-api**: -- Port `3999` are exposed to `localhost` +- Port `3999` is exposed on `localhost` ```bash -curl -sL localhost:3999/v2/info | jq +curl -sL localhost:3999 | jq -r ``` **proxy**: -- Port `80` is exposed to `localhost` +- Port `80` is exposed on `localhost` ```bash -curl -sL localhost/v2/info | jq -curl -sL localhost/ | jq +curl -sL localhost/v2/info | jq -r +curl -sL localhost | jq -r ``` --- ## 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 -``` +:::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): ::: --- - -## **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 From 15cbc43722f1ec0eaa98dfd602491da39b29c759 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:41:24 +0100 Subject: [PATCH 0269/1444] New translations index.md (Japanese) --- .../current/clarity/index.md | 58 +++++++++++++++++++ 1 file changed, 58 insertions(+) create mode 100644 i18n/ja/docusaurus-plugin-content-docs/current/clarity/index.md diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/clarity/index.md b/i18n/ja/docusaurus-plugin-content-docs/current/clarity/index.md new file mode 100644 index 0000000000..903de93a45 --- /dev/null +++ b/i18n/ja/docusaurus-plugin-content-docs/current/clarity/index.md @@ -0,0 +1,58 @@ +--- +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?2 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. If you are unsure what this means, let it not worry you for now. The serious advantage of decidability will become more apparent over time. + +### 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. From 6917481debaace28c62798c9e08748ff9e0f1c41 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:41:26 +0100 Subject: [PATCH 0270/1444] New translations index.md (Japanese) --- .../current/stacks-academy/index.md | 11 +++++++++++ 1 file changed, 11 insertions(+) create mode 100644 i18n/ja/docusaurus-plugin-content-docs/current/stacks-academy/index.md diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/stacks-academy/index.md b/i18n/ja/docusaurus-plugin-content-docs/current/stacks-academy/index.md new file mode 100644 index 0000000000..a5bdb3c790 --- /dev/null +++ b/i18n/ja/docusaurus-plugin-content-docs/current/stacks-academy/index.md @@ -0,0 +1,11 @@ +--- +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. From bc938cb1055da0a596b300b668a46e08b5155dcd Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:41:27 +0100 Subject: [PATCH 0271/1444] New translations proof-of-transfer.md (Japanese) --- .../stacks-academy/proof-of-transfer.md | 83 +++++++++++++++++++ 1 file changed, 83 insertions(+) create mode 100644 i18n/ja/docusaurus-plugin-content-docs/current/stacks-academy/proof-of-transfer.md diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/stacks-academy/proof-of-transfer.md b/i18n/ja/docusaurus-plugin-content-docs/current/stacks-academy/proof-of-transfer.md new file mode 100644 index 0000000000..50f4b739d6 --- /dev/null +++ b/i18n/ja/docusaurus-plugin-content-docs/current/stacks-academy/proof-of-transfer.md @@ -0,0 +1,83 @@ +--- +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. From 370849da06f1ed1cfbf9c655cb4b7926d0e768fb Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:41:27 +0100 Subject: [PATCH 0272/1444] New translations what-is-stacks.md (Japanese) --- .../current/stacks-academy/what-is-stacks.md | 102 ++++++++++++++++++ 1 file changed, 102 insertions(+) create mode 100644 i18n/ja/docusaurus-plugin-content-docs/current/stacks-academy/what-is-stacks.md diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/stacks-academy/what-is-stacks.md b/i18n/ja/docusaurus-plugin-content-docs/current/stacks-academy/what-is-stacks.md new file mode 100644 index 0000000000..94277da8a9 --- /dev/null +++ b/i18n/ja/docusaurus-plugin-content-docs/current/stacks-academy/what-is-stacks.md @@ -0,0 +1,102 @@ +--- +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. + +There's a lot of jargon, possible assumptions, controversy, and cool technology wrapped up in those statements. So let's get started by getting a 30,000 foot view of what exactly Stacks is. + +## Stacks Explained in (Slightly Less Than) 10 Minutes + +
+ +
+ +## 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, Stacks takes a different approach. + +## 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). + +By taking this 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 with some unique properties, like having its own token, that allow it to maintain a historical ledger of all of its transactions and operate with its own security budget. + +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_. + +Nope. 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. From ade0b6960cfc0e269a06e44a7912d4a25c9636dc Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:41:28 +0100 Subject: [PATCH 0273/1444] New translations community-tutorials.md (Japanese) --- .../current/tutorials/community-tutorials.md | 24 +++++++++++++++++++ 1 file changed, 24 insertions(+) create mode 100644 i18n/ja/docusaurus-plugin-content-docs/current/tutorials/community-tutorials.md diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/tutorials/community-tutorials.md b/i18n/ja/docusaurus-plugin-content-docs/current/tutorials/community-tutorials.md new file mode 100644 index 0000000000..a4f3d970ca --- /dev/null +++ b/i18n/ja/docusaurus-plugin-content-docs/current/tutorials/community-tutorials.md @@ -0,0 +1,24 @@ +--- +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/) From 8f552330570876747856dc04f5698ab547768ead Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:41:29 +0100 Subject: [PATCH 0274/1444] New translations hello-stacks.md (Japanese) --- .../current/tutorials/hello-stacks.md | 759 ++++++++++++++++++ 1 file changed, 759 insertions(+) create mode 100644 i18n/ja/docusaurus-plugin-content-docs/current/tutorials/hello-stacks.md diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/tutorials/hello-stacks.md b/i18n/ja/docusaurus-plugin-content-docs/current/tutorials/hello-stacks.md new file mode 100644 index 0000000000..a0a442d135 --- /dev/null +++ b/i18n/ja/docusaurus-plugin-content-docs/current/tutorials/hello-stacks.md @@ -0,0 +1,759 @@ +--- +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. From 44375ae7457927e2ef3826492bd6976167edaf9d Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:41:30 +0100 Subject: [PATCH 0275/1444] New translations index.md (Japanese) --- .../current/tutorials/index.md | 11 +++++++++++ 1 file changed, 11 insertions(+) create mode 100644 i18n/ja/docusaurus-plugin-content-docs/current/tutorials/index.md diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/tutorials/index.md b/i18n/ja/docusaurus-plugin-content-docs/current/tutorials/index.md new file mode 100644 index 0000000000..1d544c7bc1 --- /dev/null +++ b/i18n/ja/docusaurus-plugin-content-docs/current/tutorials/index.md @@ -0,0 +1,11 @@ +--- +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. From b7d5bd90cfe9390d68a967815bde9ba98e4c012a Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:41:31 +0100 Subject: [PATCH 0276/1444] New translations satoshis-ridge.md (Japanese) --- .../current/tutorials/satoshis-ridge.md | 75 +++++++++++++++++++ 1 file changed, 75 insertions(+) create mode 100644 i18n/ja/docusaurus-plugin-content-docs/current/tutorials/satoshis-ridge.md diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/tutorials/satoshis-ridge.md b/i18n/ja/docusaurus-plugin-content-docs/current/tutorials/satoshis-ridge.md new file mode 100644 index 0000000000..596339ae74 --- /dev/null +++ b/i18n/ja/docusaurus-plugin-content-docs/current/tutorials/satoshis-ridge.md @@ -0,0 +1,75 @@ +--- +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 arguable one of its strengths. + +Instead, we need to create separate layers that add additional functionality without modify 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. From f50233c893fd6f0fb78b2ddd84190e963c8ec843 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:41:32 +0100 Subject: [PATCH 0277/1444] New translations crash-course.md (Japanese) --- .../current/clarity/crash-course.md | 122 ++++++++++++++++++ 1 file changed, 122 insertions(+) create mode 100644 i18n/ja/docusaurus-plugin-content-docs/current/clarity/crash-course.md diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/clarity/crash-course.md b/i18n/ja/docusaurus-plugin-content-docs/current/clarity/crash-course.md new file mode 100644 index 0000000000..5b27a3c275 --- /dev/null +++ b/i18n/ja/docusaurus-plugin-content-docs/current/clarity/crash-course.md @@ -0,0 +1,122 @@ +--- +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.md). + +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. + +```clojure +(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: + +```clojure +(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. From 279afc539ba97dc07bc0a0ed0150e87543135663 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:41:33 +0100 Subject: [PATCH 0278/1444] New translations sample-contracts.md (Japanese) --- .../current/clarity/sample-contracts.md | 14 ++++++++++++++ 1 file changed, 14 insertions(+) create mode 100644 i18n/ja/docusaurus-plugin-content-docs/current/clarity/sample-contracts.md diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/clarity/sample-contracts.md b/i18n/ja/docusaurus-plugin-content-docs/current/clarity/sample-contracts.md new file mode 100644 index 0000000000..adb12a58fd --- /dev/null +++ b/i18n/ja/docusaurus-plugin-content-docs/current/clarity/sample-contracts.md @@ -0,0 +1,14 @@ +--- +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) From 035254ae11bfc075883ea1a4190fc09d77ab2d35 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:41:33 +0100 Subject: [PATCH 0279/1444] New translations index.md (Japanese) --- .../current/cookbook/index.md | 64 +++++++++++++++++++ 1 file changed, 64 insertions(+) create mode 100644 i18n/ja/docusaurus-plugin-content-docs/current/cookbook/index.md diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/cookbook/index.md b/i18n/ja/docusaurus-plugin-content-docs/current/cookbook/index.md new file mode 100644 index 0000000000..a2b0e42eea --- /dev/null +++ b/i18n/ja/docusaurus-plugin-content-docs/current/cookbook/index.md @@ -0,0 +1,64 @@ +--- +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 + +Swapping between Bitcoin and Stacks addresses + +Swapping between xBTC and BTC + +Verifying a transaction on the BTC chain + +## 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 + +Airdropping an NFT to a Bitcoin address + +## Stacking and Mining + +Simple stacking pool + +Continuous stacking + +Simple mining pool + +Proof of PoX payout + +## Oracles + +Creating a simple BTC price oracle + +## Frontend + +[Post conditions with Stacks.js](./post-conditions) + +[Authentication with Stacks.js](./stacks-js-auth) + +[Sending transactions with Stacks.js](./stacks-js-sending-transactions) + +## Complete Apps + +[Sup](https://github.com/kenrogers/sup) + +[Hello Stacks](https://github.com/kenrogers/hello-stacks) From c7a985697390fb9596eee006e310ae9f38a2cccd Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:41:34 +0100 Subject: [PATCH 0280/1444] New translations btc-connection.md (Japanese) --- .../current/stacks-academy/btc-connection.md | 196 ++++++++++++++++++ 1 file changed, 196 insertions(+) create mode 100644 i18n/ja/docusaurus-plugin-content-docs/current/stacks-academy/btc-connection.md diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/stacks-academy/btc-connection.md b/i18n/ja/docusaurus-plugin-content-docs/current/stacks-academy/btc-connection.md new file mode 100644 index 0000000000..b4db915969 --- /dev/null +++ b/i18n/ja/docusaurus-plugin-content-docs/current/stacks-academy/btc-connection.md @@ -0,0 +1,196 @@ +--- +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. + +## Stacks Among Other Bitcoin Layers + +In the [last section](./what-is-stacks.md) we covered what Stacks actually is and what problem it is solving, but this is not a new problem. The Bitcoin write problem has been a bit of a holy grail problem in the crypto world for a while now. + +Bitcoin is the OG cryptocurrency and has the largest market cap, but it also some of the least functionality, which means if we want to make it a productive asset and use it to build a decentralized economy, we need to take a layered approach and let Bitcoin do what it does best, while creating additional layers on top of it to add functionality. + +So how does Stacks compare to some of the other approaches to layering on top of Bitcoin? + +### 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. + +## 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. + +But because it has its own execution environment and smart contract state to maintain, it needs a token to incentivize maintenance of the network. + +But it goes further than that. It is possible to build a system like this without a token using something like merge-mining or a sidechain, but then we lose out on the additional benefit of having the chain state's safety underpinned by its entire token economy's value. + +In the case of Stacks, the safety and liveness of the chain are underpinned by this value, and the stacking mechanism incentivizes network members to increase this value. + +From Jude Nelson, Stacks core developer: + +"How hard is it to cause a safety failure (i.e. a double-spend via a reorg) on just the canonical Stacks chain fork? Anyone can become a miner by spending BTC, so without loss of generality, reverting the last block on the canonical chain is at least as hard in expectation as spending more BTC than the rest of the miners combined for that block. Because each Bitcoin block selects at most one Stacks block, the act of reorging the canonical Stacks chain back N blocks is the act of winning at least N + 1 blocks built off of a common ancestor that is N blocks deep. This is a lower bound on the number of Bitcoin blocks mined during which a reorg needs to take place — in practice, honest miners will keep working on the canonical chain, and will win some Stacks blocks of their own, which in turn increases the number of Stacks blocks the reorging miners must win. + +How costly is it to carry out a reorg of N blocks? It’s a function of how valuable STX is relative to BTC — the more valuable STX are, the more BTC honest miners are committing to mining (this has borne out in practice), and thus the more BTC a reorging miner must commit. Therefore, the cost of a reorg is a function of the value of STX. + +This is similar to the economic security of a PoW blockchain. Like in PoW, each fork of the Stacks chain has its own independent “security budget” — an attacker must out-spend the security budget to carry out a reorg, and the security budget is a function of the block rewards. In PoX, the only difference is that the miners spend another blockchain’s tokens (BTC in Stacks’ case) instead of energy. Therefore, Stacks can’t be a sidechain, a drivechain, or a merge-mined chain, because none of these other systems’ security budgets are a function of their tokens’ worth. Sidechains, drivechains, and merged-mined chains all rely on external miners for their safety, since their safety is guaranteed in part by external miners validating their blocks. The onus on these systems is to get external miners to care enough to do so, and in the case of sidechains, drivechains, and blind merged-mined chains, there is an additional onus to encourage their nodes to mine blocks at all (since there is no on-chain reward for them to earn by doing so). By contrast, disinterested Bitcoin miners neither assist nor prevent a reorg in PoX — they only record the history of all Stacks forks. + +PoX offers two additional, unique security properties on top of PoW. First, no matter how much BTC a reorging miner can commit, the act of executing a reorg is going to be time-consuming. Unless the attacker can attack the Bitcoin chain itself by quickly producing a better Bitcoin fork, a reorging miner must sustain the attack for at least N + 1 Bitcoin blocks. This gives honest miners and users ample time to notice and react to the reorg attempt. + +Second, the history of block production in all Stacks forks is embedded within Bitcoin. This allows the system to leverage Bitcoin’s security budget in order to ensure that all forks are public. This is because the act of producing a hidden Stacks fork, where the fork’s block hashes are not known to the honest miners, is the act of producing a hidden canonical Bitcoin fork. Therefore, the act of producing a hidden Stacks fork is at least as hard as reorging the Bitcoin chain. A PoX chain leverages this property not to prevent reorgs, but to make reorgs unprofitable. + +By anchoring blocks to an existing blockchain, a PoX chain forces reorgs to happen out in the open, thereby giving advance warning to all honest network participants when they happen. Honest miners, users, and exchanges will see the PoX transactions for reorg attempts on the existing blockchain, and adapt their behaviors accordingly: honest miners will increase their commitments, and users and exchanges will require more confirmations for transactions. This makes the act of carrying out a reorg while also making a profit much more challenging, since malicious reorgs — like selfish mining and double-spending — rely on secrecy to work effectively. Specific to Stacks, miners are additionally required to mine for a “warm-up” period of two blocks, during which they must spend BTC at their target commit levels but will not win any Stacks blocks. So, a high-budget reorg attempt will not only be costly, but will also alert the rest of the network before the damage is done." + +- [What Kind of Blockchain is Stacks?](https://stacks.org/stacks-blockchain) + +## 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) From 0e8d9af0ad26bcc76318130d1813a567dc84067e Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:41:35 +0100 Subject: [PATCH 0281/1444] New translations post-conditions.md (Japanese) --- .../current/stacks-academy/post-conditions.md | 39 +++++++++++++++++++ 1 file changed, 39 insertions(+) create mode 100644 i18n/ja/docusaurus-plugin-content-docs/current/stacks-academy/post-conditions.md diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/stacks-academy/post-conditions.md b/i18n/ja/docusaurus-plugin-content-docs/current/stacks-academy/post-conditions.md new file mode 100644 index 0000000000..bb0727194f --- /dev/null +++ b/i18n/ja/docusaurus-plugin-content-docs/current/stacks-academy/post-conditions.md @@ -0,0 +1,39 @@ +--- +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). From af96e9d0c697dd37e4c49e7544fea5dc1a4ce208 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:41:36 +0100 Subject: [PATCH 0282/1444] New translations creating-an-ft.md (Japanese) --- .../current/cookbook/creating-an-ft.md | 99 +++++++++++++++++++ 1 file changed, 99 insertions(+) create mode 100644 i18n/ja/docusaurus-plugin-content-docs/current/cookbook/creating-an-ft.md diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/cookbook/creating-an-ft.md b/i18n/ja/docusaurus-plugin-content-docs/current/cookbook/creating-an-ft.md new file mode 100644 index 0000000000..4e3bad99d2 --- /dev/null +++ b/i18n/ja/docusaurus-plugin-content-docs/current/cookbook/creating-an-ft.md @@ -0,0 +1,99 @@ +--- +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) + ) +) +``` From 01e9e5331cf366e861892480c2465fc91c8bf190 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:41:36 +0100 Subject: [PATCH 0283/1444] New translations creating-an-nft.md (Japanese) --- .../current/cookbook/creating-an-nft.md | 87 +++++++++++++++++++ 1 file changed, 87 insertions(+) create mode 100644 i18n/ja/docusaurus-plugin-content-docs/current/cookbook/creating-an-nft.md diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/cookbook/creating-an-nft.md b/i18n/ja/docusaurus-plugin-content-docs/current/cookbook/creating-an-nft.md new file mode 100644 index 0000000000..08faf9393a --- /dev/null +++ b/i18n/ja/docusaurus-plugin-content-docs/current/cookbook/creating-an-nft.md @@ -0,0 +1,87 @@ +--- +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 +Code for this recipe has been pulled from [this NFT tutorial](https://blog.developerdao.com/building-an-nft-with-stacks-and-clarity) from Developer DAO. +::: + +## 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) + ) +) +``` From e465c08a11f366fd6426b682c589f40eaed36e52 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:41:37 +0100 Subject: [PATCH 0284/1444] New translations post-conditions.md (Japanese) --- .../current/cookbook/post-conditions.md | 136 ++++++++++++++++++ 1 file changed, 136 insertions(+) create mode 100644 i18n/ja/docusaurus-plugin-content-docs/current/cookbook/post-conditions.md diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/cookbook/post-conditions.md b/i18n/ja/docusaurus-plugin-content-docs/current/cookbook/post-conditions.md new file mode 100644 index 0000000000..571fc20d48 --- /dev/null +++ b/i18n/ja/docusaurus-plugin-content-docs/current/cookbook/post-conditions.md @@ -0,0 +1,136 @@ +--- +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. From 0b63956ea867ef7c7d94dfb23878979a93285672 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:41:38 +0100 Subject: [PATCH 0285/1444] New translations stacks-js-auth.md (Japanese) --- .../current/cookbook/stacks-js-auth.md | 98 +++++++++++++++++++ 1 file changed, 98 insertions(+) create mode 100644 i18n/ja/docusaurus-plugin-content-docs/current/cookbook/stacks-js-auth.md diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/cookbook/stacks-js-auth.md b/i18n/ja/docusaurus-plugin-content-docs/current/cookbook/stacks-js-auth.md new file mode 100644 index 0000000000..89d1f06e00 --- /dev/null +++ b/i18n/ja/docusaurus-plugin-content-docs/current/cookbook/stacks-js-auth.md @@ -0,0 +1,98 @@ +--- +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 && ( + + ); +} +``` From 08f5a2c704bf54d8b03f6419b9f2f1d9f0a6d72a Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:41:39 +0100 Subject: [PATCH 0286/1444] New translations stacks-js-sending-transactions.md (Japanese) --- .../stacks-js-sending-transactions.md | 55 +++++++++++++++++++ 1 file changed, 55 insertions(+) create mode 100644 i18n/ja/docusaurus-plugin-content-docs/current/cookbook/stacks-js-sending-transactions.md diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/cookbook/stacks-js-sending-transactions.md b/i18n/ja/docusaurus-plugin-content-docs/current/cookbook/stacks-js-sending-transactions.md new file mode 100644 index 0000000000..849c7d1f42 --- /dev/null +++ b/i18n/ja/docusaurus-plugin-content-docs/current/cookbook/stacks-js-sending-transactions.md @@ -0,0 +1,55 @@ +--- +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. From 627f545a3de69aae9267ba3670b74abe4f820add Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:41:40 +0100 Subject: [PATCH 0287/1444] New translations _category_.json (Japanese) --- .../current/clarity/noteworthy-contracts/_category_.json | 8 ++++++++ 1 file changed, 8 insertions(+) create mode 100644 i18n/ja/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/_category_.json diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/_category_.json b/i18n/ja/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/_category_.json new file mode 100644 index 0000000000..f5de305558 --- /dev/null +++ b/i18n/ja/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/_category_.json @@ -0,0 +1,8 @@ +{ + "label": "Noteworthy Contracts", + "position": 4, + "link": { + "type": "generated-index", + "description": "Specific deployed Clarity Contracts worth mentioning." + } +} \ No newline at end of file From ae69058bbba4375e3e83c8d6488dda4999815afc Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:41:41 +0100 Subject: [PATCH 0288/1444] New translations bns-contract.md (Japanese) --- .../noteworthy-contracts/bns-contract.md | 519 ++++++++++++++++++ 1 file changed, 519 insertions(+) create mode 100644 i18n/ja/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/bns-contract.md diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/bns-contract.md b/i18n/ja/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/bns-contract.md new file mode 100644 index 0000000000..a7770b7d24 --- /dev/null +++ b/i18n/ja/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/bns-contract.md @@ -0,0 +1,519 @@ +--- +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 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` From b62efdbbf29820d566bae888d5e1b0f88168b81f Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:41:41 +0100 Subject: [PATCH 0289/1444] New translations xbtc.md (Japanese) --- .../clarity/noteworthy-contracts/xbtc.md | 28 +++++++++++++++++++ 1 file changed, 28 insertions(+) create mode 100644 i18n/ja/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/xbtc.md diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/xbtc.md b/i18n/ja/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/xbtc.md new file mode 100644 index 0000000000..e535dcf260 --- /dev/null +++ b/i18n/ja/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/xbtc.md @@ -0,0 +1,28 @@ +--- +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) From 54722c9b9514083ed3b998f68ece0c2cda704f93 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:41:42 +0100 Subject: [PATCH 0290/1444] New translations index.md (Japanese) --- .../current/glossary/index.md | 284 ++++++++++++++++++ 1 file changed, 284 insertions(+) create mode 100644 i18n/ja/docusaurus-plugin-content-docs/current/glossary/index.md diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/glossary/index.md b/i18n/ja/docusaurus-plugin-content-docs/current/glossary/index.md new file mode 100644 index 0000000000..419c0e0d73 --- /dev/null +++ b/i18n/ja/docusaurus-plugin-content-docs/current/glossary/index.md @@ -0,0 +1,284 @@ +--- +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. From e7dbc2182a4ac8eaab582f9ae86b970feffb2c42 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:41:43 +0100 Subject: [PATCH 0291/1444] New translations quicknode.md (Japanese) --- .../current/nodes-and-miners/quicknode.md | 45 +++++++++++++++++++ 1 file changed, 45 insertions(+) create mode 100644 i18n/ja/docusaurus-plugin-content-docs/current/nodes-and-miners/quicknode.md diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/nodes-and-miners/quicknode.md b/i18n/ja/docusaurus-plugin-content-docs/current/nodes-and-miners/quicknode.md new file mode 100644 index 0000000000..1281964689 --- /dev/null +++ b/i18n/ja/docusaurus-plugin-content-docs/current/nodes-and-miners/quicknode.md @@ -0,0 +1,45 @@ +--- +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. From 55f918bc9c8ab0bf2692119d808d03042bb57612 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:41:44 +0100 Subject: [PATCH 0292/1444] New translations defi.md (Japanese) --- .../current/services-using-stacks/defi.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) 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 index 51defacba7..58717a3234 100644 --- 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 @@ -26,7 +26,7 @@ Please edit this page to add any relevant new site that we are missing. ## Lnswap -[LNSWAP](https://www.lnswap.org). Non custiodial crypto currency exchange +[LNSWAP](https://www.lnswap.org). Non-custodial crypto currency exchange ![](/img/sh_lnswap.png) @@ -41,4 +41,3 @@ Please edit this page to add any relevant new site that we are missing. [Stackswap](https://app.stackswap.org/v2) ![](/img/sh_stackswap.png) - From 6e1747399eb0f4987af21ab89c8264aa4d9cc47f Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:41:45 +0100 Subject: [PATCH 0293/1444] New translations more.md (Japanese) --- .../current/services-using-stacks/more.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) 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 index df0b3e2254..1e14b9a5a5 100644 --- 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 @@ -18,6 +18,6 @@ Please edit this page to add any relevant new site that we are missing. ## Sigle -[Sigle](https://www.sigle.io/) is a decentralised and open source web 3 writing platform. +[Sigle](https://www.sigle.io/) is a decentralized and open source web 3 writing platform. -![](/img/sh_sigle.png) \ No newline at end of file +![](/img/sh_sigle.png) From 2d6a2362a41ee136734cd6cd999795aab55a06ef Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:41:46 +0100 Subject: [PATCH 0294/1444] New translations nft.md (Japanese) --- .../current/services-using-stacks/nft.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) 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 index abb770663c..d582604854 100644 --- 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 @@ -15,6 +15,7 @@ Please edit this page to add any relevant new site that we are missing. ![website-screenshot](/img/sh_nft_byzantion.png) ### [Gamma](https://gamma.io/) + ![website-screenshot](/img/sh_nft_gamma.png) ### [Megapont](https://www.megapont.com/) @@ -35,4 +36,4 @@ Please edit this page to add any relevant new site that we are missing. ### [Superfandom](https://superfandom.io/) -![website-screenshot](/img/sh_superfandom.png) \ No newline at end of file +![website-screenshot](/img/sh_superfandom.png) From 708ff647ec01e085f2d7204bcc3c4a1470c6095b Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:41:47 +0100 Subject: [PATCH 0295/1444] New translations stacks-info-sites.md (Japanese) --- .../current/services-using-stacks/stacks-info-sites.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) 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 index 35ced8dac6..54f6823e33 100644 --- 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 @@ -30,7 +30,7 @@ Please edit this page to add any relevant new site that we are missing. ![website-screenshot](/img/sh_stxstats.png) -### [Novuminsights](https://stacks.novuminsights.com/health) +### [Novum Insights](https://stacks.novuminsights.com/health) ![website-screenshot](/img/sh_novuminsights.png) From e482c286f689accc61cf709d43949b8c5f301493 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:41:48 +0100 Subject: [PATCH 0296/1444] New translations wallets.md (Japanese) --- .../current/services-using-stacks/wallets.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) 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 index e5ea6c5b45..2d3fcc85f2 100644 --- 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 @@ -15,6 +15,7 @@ Please edit this page to add any relevant new site that we are missing. [Blockchain.com](https://www.blockchain.com/wallet) ![](/img/sh_blockchain.png) + ## Boom [Boom](https://boom.money) @@ -26,6 +27,7 @@ Please edit this page to add any relevant new site that we are missing. [D'CENT](https://dcentwallet.com) ![](/img/sh_dcent.png) + ## Hiro Wallet [Hiro Wallet](https://www.hiro.so/wallet) @@ -48,4 +50,4 @@ Please edit this page to add any relevant new site that we are missing. [Wise](https://wiseapp.id) -![](/img/sh_wiseapp.png) \ No newline at end of file +![](/img/sh_wiseapp.png) From ce3db2597739b80360711380c47e40d6ffdb0886 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:41:48 +0100 Subject: [PATCH 0297/1444] New translations whitepapers.md (Japanese) --- .../current/stacks-academy/whitepapers.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) create mode 100644 i18n/ja/docusaurus-plugin-content-docs/current/stacks-academy/whitepapers.md diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/stacks-academy/whitepapers.md b/i18n/ja/docusaurus-plugin-content-docs/current/stacks-academy/whitepapers.md new file mode 100644 index 0000000000..0e564fbf44 --- /dev/null +++ b/i18n/ja/docusaurus-plugin-content-docs/current/stacks-academy/whitepapers.md @@ -0,0 +1,12 @@ +--- +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) From 5acc863f6dc39a4c6320f6ca18bf6fe25c51e5f7 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:41:49 +0100 Subject: [PATCH 0298/1444] New translations stacking-contract.md (Japanese) --- .../noteworthy-contracts/stacking-contract.md | 352 ++++++++++++++++++ 1 file changed, 352 insertions(+) create mode 100644 i18n/ja/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/stacking-contract.md diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/stacking-contract.md b/i18n/ja/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/stacking-contract.md new file mode 100644 index 0000000000..c0027256cd --- /dev/null +++ b/i18n/ja/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/stacking-contract.md @@ -0,0 +1,352 @@ +--- +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. 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` From c8bb9099fc2357aeae532a931251bdf371a71634 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:41:50 +0100 Subject: [PATCH 0299/1444] New translations index.md (Japanese) --- .../current/next-steps/index.md | 39 +++++++++++++++++++ 1 file changed, 39 insertions(+) create mode 100644 i18n/ja/docusaurus-plugin-content-docs/current/next-steps/index.md diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/next-steps/index.md b/i18n/ja/docusaurus-plugin-content-docs/current/next-steps/index.md new file mode 100644 index 0000000000..00ddec9178 --- /dev/null +++ b/i18n/ja/docusaurus-plugin-content-docs/current/next-steps/index.md @@ -0,0 +1,39 @@ +--- +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) From c5cf995a4e7325b8de76aa20d759baa72e35fe85 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:41:51 +0100 Subject: [PATCH 0300/1444] New translations sips.md (Japanese) --- .../current/stacks-academy/sips.md | 52 +++++++++++++++++++ 1 file changed, 52 insertions(+) create mode 100644 i18n/ja/docusaurus-plugin-content-docs/current/stacks-academy/sips.md diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/stacks-academy/sips.md b/i18n/ja/docusaurus-plugin-content-docs/current/stacks-academy/sips.md new file mode 100644 index 0000000000..aa2db18e62 --- /dev/null +++ b/i18n/ja/docusaurus-plugin-content-docs/current/stacks-academy/sips.md @@ -0,0 +1,52 @@ +--- +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/IJ15791776) 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-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. From 781d7810de74d9d758b94ec15fe13bfeb41633b0 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:41:52 +0100 Subject: [PATCH 0301/1444] New translations hosted-nodes.md (Japanese) --- .../current/nodes-and-miners/hosted-nodes.md | 25 +++++++++++++++++++ 1 file changed, 25 insertions(+) create mode 100644 i18n/ja/docusaurus-plugin-content-docs/current/nodes-and-miners/hosted-nodes.md diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/nodes-and-miners/hosted-nodes.md b/i18n/ja/docusaurus-plugin-content-docs/current/nodes-and-miners/hosted-nodes.md new file mode 100644 index 0000000000..12d86c7ee2 --- /dev/null +++ b/i18n/ja/docusaurus-plugin-content-docs/current/nodes-and-miners/hosted-nodes.md @@ -0,0 +1,25 @@ +--- +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. From d7aedbb6182328cd354a0222b59a601153087ede Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:41:53 +0100 Subject: [PATCH 0302/1444] New translations authentication.md (Korean) --- .../current/stacks-academy/authentication.md | 63 +++++++++++++++++++ 1 file changed, 63 insertions(+) create mode 100644 i18n/ko/docusaurus-plugin-content-docs/current/stacks-academy/authentication.md diff --git a/i18n/ko/docusaurus-plugin-content-docs/current/stacks-academy/authentication.md b/i18n/ko/docusaurus-plugin-content-docs/current/stacks-academy/authentication.md new file mode 100644 index 0000000000..8152a401f9 --- /dev/null +++ b/i18n/ko/docusaurus-plugin-content-docs/current/stacks-academy/authentication.md @@ -0,0 +1,63 @@ +--- +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/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. From 5c7c0e6fc05cf0dd155c1a4985813780b59541d8 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:41:54 +0100 Subject: [PATCH 0303/1444] New translations bns.md (Korean) --- .../current/stacks-academy/bns.md | 242 ++++++++++++++++++ 1 file changed, 242 insertions(+) create mode 100644 i18n/ko/docusaurus-plugin-content-docs/current/stacks-academy/bns.md diff --git a/i18n/ko/docusaurus-plugin-content-docs/current/stacks-academy/bns.md b/i18n/ko/docusaurus-plugin-content-docs/current/stacks-academy/bns.md new file mode 100644 index 0000000000..4c89d9e56c --- /dev/null +++ b/i18n/ko/docusaurus-plugin-content-docs/current/stacks-academy/bns.md @@ -0,0 +1,242 @@ +--- +title: Blockchain Naming System +description: Binds Stacks usernames to off-chain state +sidebar_position: 8 +--- + +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 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). From 82dcc47ad7bb3dd9819576a9b2b6fcd6e7f21b48 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:41:55 +0100 Subject: [PATCH 0304/1444] New translations docs.md (Korean) --- .../current/contribute/docs.md | 24 ++++++++++++------- 1 file changed, 15 insertions(+), 9 deletions(-) diff --git a/i18n/ko/docusaurus-plugin-content-docs/current/contribute/docs.md b/i18n/ko/docusaurus-plugin-content-docs/current/contribute/docs.md index 77705451b8..b2fef628f9 100644 --- a/i18n/ko/docusaurus-plugin-content-docs/current/contribute/docs.md +++ b/i18n/ko/docusaurus-plugin-content-docs/current/contribute/docs.md @@ -7,7 +7,7 @@ description: Learn how this site is built, and how you can contribute to it. 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). +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/). @@ -15,7 +15,7 @@ Don't want to learn it? No need to. Write [in plain text an issue on Github](htt :::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 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). @@ -24,28 +24,32 @@ To add new content, they are two different ways to do it, the [easy way](#easy-w [**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. +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 yourhanges in real time. + - `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. -## Aditional information +## 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 ``` @@ -54,8 +58,8 @@ Before running this command for the first time you will need to run `npm install 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 ``` @@ -91,7 +95,7 @@ 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. +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 @@ -124,6 +128,7 @@ And execute prettier with the following command: npx prettier --write mynewfiletocheck.md ``` --> + ### 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. @@ -138,6 +143,7 @@ To write a code block, you need to wrap your code in ` ```language `, and end yo (define-public (get-counter) (ok (var-get counter))) ``` + ### Admonitions You can use the following admonitions to highlight content. @@ -204,4 +210,4 @@ Some **content** with _markdown_ `syntax`. Some **content** with _markdown_ `syntax`. -::: \ No newline at end of file +::: From 8c736dda6a1d6e6651a23bcfc5447e65f070f240 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:41:56 +0100 Subject: [PATCH 0305/1444] New translations translations.md (Korean) --- .../current/contribute/translations.md | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/i18n/ko/docusaurus-plugin-content-docs/current/contribute/translations.md b/i18n/ko/docusaurus-plugin-content-docs/current/contribute/translations.md index bd9a452333..fe8f8c6027 100644 --- a/i18n/ko/docusaurus-plugin-content-docs/current/contribute/translations.md +++ b/i18n/ko/docusaurus-plugin-content-docs/current/contribute/translations.md @@ -1,25 +1,24 @@ --- title: Contribute with translations -description: Want to help tranlating these docs to your local language? +description: Want to help translating 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. +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 Crodin intead. +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 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 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) From 21b0b797935ba628f2495f5571ead8916acb3e93 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:41:58 +0100 Subject: [PATCH 0306/1444] New translations gaia-on-ec2.md (Korean) --- .../current/gaia/gaia-on-ec2.md | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) 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 index 2067e7d57c..3f58ca5e68 100644 --- 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 @@ -26,9 +26,10 @@ Use a link in the table to launch the [CloudFormation](https://console.aws.amazo ### Step 2 - Setup stack using template -You need to configure the template with the appropiate values for your hub and domain it runs on. +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 ``` @@ -52,7 +53,7 @@ Specify the stack details and then click `Next`: ![Specify template](/img/cloudf | 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`. | +| 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 | @@ -93,7 +94,9 @@ ssh -i admin@ 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 +![](/img/cloudformation-gaia-template1-designer.png) From 6f19a9fdcf2d81618df47bff31330b4062f86332 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:41:59 +0100 Subject: [PATCH 0307/1444] New translations gaia.md (Korean) --- .../current/gaia/gaia.md | 12 +++++++++--- 1 file changed, 9 insertions(+), 3 deletions(-) diff --git a/i18n/ko/docusaurus-plugin-content-docs/current/gaia/gaia.md b/i18n/ko/docusaurus-plugin-content-docs/current/gaia/gaia.md index 1070857350..f86a0d61dc 100644 --- a/i18n/ko/docusaurus-plugin-content-docs/current/gaia/gaia.md +++ b/i18n/ko/docusaurus-plugin-content-docs/current/gaia/gaia.md @@ -1,14 +1,20 @@ --- title: Gaia description: Decentralized storage architecture for off-chain data -sidebar_position: 5 +sidebar_position: 6 tags: - gaia --- ## Introduction -Apps built with the Stacks blockchain store off-chain data using a storage system called Gaia. +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. @@ -38,7 +44,7 @@ The Stacks blockchain stores only identity data. Data created by the actions of 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) +![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. From d7dfe7a4e8bb87d433a92faffc0b0247afaf9d62 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:42:00 +0100 Subject: [PATCH 0308/1444] New translations setup-linux.md (Korean) --- .../current/gaia/setup-linux.md | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) 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 index db427f890a..2c0ca2b92e 100644 --- a/i18n/ko/docusaurus-plugin-content-docs/current/gaia/setup-linux.md +++ b/i18n/ko/docusaurus-plugin-content-docs/current/gaia/setup-linux.md @@ -1,6 +1,6 @@ --- 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. +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 @@ -19,8 +19,7 @@ This configuration will setup the following 4 docker containers: 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: +**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 @@ -48,8 +47,7 @@ chmod +x ${DESTINATION_DC}/docker-compose 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. +**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 From 5a4bb466b6388edaa0dfe6d6453d5c09723c0864 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:42:02 +0100 Subject: [PATCH 0309/1444] New translations digitalocean.md (Korean) --- .../current/nodes-and-miners/digitalocean.md | 41 +++++++++++-------- 1 file changed, 25 insertions(+), 16 deletions(-) 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 index dd7194f504..15df918d04 100644 --- 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 @@ -1,28 +1,30 @@ --- -title: Stacks on DigitalOcean +title: Run a Node with Digital Ocean description: A guide to setup Stacks on DigitalOcean -sidebar_position: 4 +sidebar_position: 2 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). +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`. +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 plan that meets the minimum requirements) and your prefered datacenter region. ![](/img/sh_digitalocean-choose-plan.png) +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 if your prefer. +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) @@ -46,41 +48,48 @@ Congratulations! You are now running the Stacks Blockchain. You can click on `Co ## 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). +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`. -Once the stacks blockchain starts to sync with peers, application ports will open and nginx port 80 will now start proxying requests. +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 v3.0.3 (master:cd0c8aef)", + "server_version": "stacks-blockchain-api v6.2.3 (master:77ab3ae2)", "status": "ready", "chain_tip": { - "block_height": 16220, - "block_hash": "0x3123fba9c0de6b569573494cf83c1d5d198a66bfd5f48ef97949b6bf11ba13be", - "index_block_hash": "0xeec960fbbd6186b4ccac85ce12adba72be497d881f81e077305c90955b51a6ae" + "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/README.md#quickstart). +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). -## API Creation +## 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 -curl -X POST -H 'Content-Type: application/json' \ +$ export TOKEN= +$ 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"}' \ + '{"name":"stacks-blockchain","region":"sfo2","size":"s-2vcpu-4gb","image":"stacksfoundation-stacksblockchain"}' \ "https://api.digitalocean.com/v2/droplets" ``` From 2dfd4dbac8748170bbe5b6d15b35521746355830 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:42:03 +0100 Subject: [PATCH 0310/1444] New translations index.md (Korean) --- .../current/nodes-and-miners/index.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) 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 index b6cbb9754a..e5f4f2c250 100644 --- 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 @@ -1,11 +1,11 @@ --- title: Nodes and Miners description: Nodes and Miners -sidebar_position: 7 +sidebar_position: 5 --- -Here are all the steps to run nodes and miners, both on mainnet and testnet. +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. -## What's a Stacks node? +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. -## What's a Stacks miner? +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. From 1ba8fe84eebaa13421ac274f5f85ae515d2444ef Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:42:04 +0100 Subject: [PATCH 0311/1444] New translations miner-mainnet.md (Korean) --- .../current/nodes-and-miners/miner-mainnet.md | 301 +++++++----------- 1 file changed, 110 insertions(+), 191 deletions(-) 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 index 061f4a2511..5afd34c23f 100644 --- 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 @@ -1,166 +1,100 @@ --- title: Mine mainnet Stacks tokens -description: Set up and run a miner on the Stacks 2.0 mainnet -sidebar_position: 5 +description: Set up and run a miner on Stacks Mainnet +sidebar_position: 6 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. +For more on the technical details of mining, please review the [mining guide](../stacks-academy/mining) -If you're interested in mining on the testnet, you can find instructions on how to do that [here](miner-testnet): +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 want to learn more about the technical details of mining, please review the [mining guide](../understand-stacks/mining): +If you're interested in mining on the Stacks testnet, you can find instructions on how to do that [here](miner-testnet): -## Running bitcoind locally +## Running a Bitcoin Mainnet Full Node -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) +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. -First, download the bitcoind software for your platform from https://bitcoin.org/en/download. +- [Ensure your computer meets the minimum hardware requirements before continuing.](https://bitcoin.org/en/bitcoin-core/features/requirements#system-requirements) -Next, start bitcoind with the following configuration: +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): -```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 -``` +:::tip It is recommened to use a persistent location for the chainstate, in the steps below we're using `/bitcoin` ::: -Finally, start bitcoind as follows: +### Update the Bitcoin Configuration File -```bash -bitcoind -conf=path/to/bitcoin.conf -``` - -It may take a few days for the node to synchronize with the Bitcoin mainnet. +Next, update the bitcoin configuration: -## 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: +- **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 -[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 = "" -... +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 ``` -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. +### Start Bitcoin -To run your miner, run this in the command line: +Finally, start bitcoin as follows (adjust the `conf` path to where it was created in the previous step, i.e. `$HOME/bitcoin.conf`): ```bash -stacks-node start --config=./testnet/stacks-node/conf/mainnet-miner-conf.toml +bitcoind -conf=$HOME/bitcoin.conf ``` -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 -``` +:::note +It will take a few days for the node to synchronize with Bitcoin mainnet. +::: -The above code will compile an optimized binary. To use it, run: +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 -cd ../.. -./target/release/stacks-node start --config=./mainnet-miner-conf.toml +$ bitcoin-cli \ + -rpcconnect=localhost \ + -rpcport=8332 \ + -rpcuser=btcuser \ + -rpcpassword=btcpassword \ +getblockchaininfo | jq .blocks +773281 ``` -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 Stacks Blockchain miner -## Running a miner in Windows +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) -### Prerequisites +_There may be some extra requirements to building, [defined here](https://github.com/stacksfoundation/miner-docs/blob/main/prerequisites.md#install-required-packages)_ -Make sure are [running a node](run-a-node) and [running bitcoind locally](#running-bitcoind-locally) before starting this tutorial. +:::tip It is recommened to use a persistent location for the chainstate, in the steps below we're using `/stacks-blockchain` ::: -### Generate keychain and get mainnet tokens in Windows +### Generate a keychain -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 cryptocurrency 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: +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 -npm install --global @stacks/cli -stx make_keychain > cli_keychain.json -type cli_keychain.json +npx @stacks/cli make_keychain 2>/dev/null | jq -r ``` -After this runs, you'll probably see some installation logs, and at the end you should see some JSON that looks like this: +After this runs, you should see some JSON printed to the screen that looks like this: ```json { @@ -174,109 +108,99 @@ After this runs, you'll probably see some installation logs, and at the end you } ``` -:::tip Check out the [Stacks CLI reference](https://docs.hiro.so/references/stacks-cli) for more details ::: +:::warning **Do not lose this information** - we'll need to use the `privateKey` and `btcAddress` fields in later steps. ::: -The above BTC address will then need to be imported into the BTC network. +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=your-user -rpcpassword=your-password importaddress +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 configuration file + + +### Update the Stacks Blockchain 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). +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`. -Update the following properties: +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] -... -# Enter your private key here -seed = "replace-with-your-private-key" -local_peer_seed = "replace-with-your-private-key" -... +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] -... -# To mine on mainnet, you need to run bitcoind locally -# Details can be found in above section, 'Running bitcoind locally' +chain = "bitcoin" +mode = "mainnet" peer_host = "127.0.0.1" -username = "" -password = "" -... +username = "" +password = "" +rpc_port = 8332 +peer_port = 8333 +satoshis_per_byte = 100 +burn_fee_cap = 20000 ``` -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 +### Start the Stacks Blockchain -To start your miner, run this in the command line: +To run your miner, run this in the command line: ```bash -stacks-node start --config=testnet/stacks-node/conf/mainnet-miner-conf.toml +stacks-node start --config=$HOME/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 +### 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 -set RUST_BACKTRACE=full; -set STACKS_LOG_DEBUG=1; -stacks-node start --config=mainnet-miner-conf.toml +STACKS_LOG_DEBUG=1 stacks-node start --config=$HOME/mainnet-miner-conf.toml ``` -## Optional: Running with Docker +--- + +## Optional: Running a Stacks Blockchain miner with Docker -Alternatively, you can run the mainnet node with Docker. +Alternatively, you can run a Stacks mainnet miner with Docker. -:::caution Ensure you have [Docker](https://docs.docker.com/get-docker/) installed on your machine. ::: +:::caution Ensure you have [Docker](https://docs.docker.com/get-docker/) installed. ::: -### Generate keychain and get tokens +### 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 +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 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: +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). -```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 = "" -... -``` +### Update Stacks Blockchain Docker Configuration File -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. +Use the steps oulined above to create the [configuration file](miner-mainnet#update-the-stacks-blockchain-configuration-file) -### Start the miner +### 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 ::: @@ -287,7 +211,8 @@ docker run -d \ --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" \ + -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 \ @@ -302,9 +227,9 @@ 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). +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 on your machine: +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) @@ -313,13 +238,7 @@ Ensure you have the following prerequisites installed on your machine: ### 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). +Use the steps [outlined above](miner-mainnet#generate-a-keychain-and-get-some-tokens) ### Install the chart and run the miner From 673edf19c3474fba7866a45aa1cbbd4d0688cdda Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:42:05 +0100 Subject: [PATCH 0312/1444] New translations miner-testnet.md (Korean) --- .../current/nodes-and-miners/miner-testnet.md | 318 +++++++----------- 1 file changed, 130 insertions(+), 188 deletions(-) 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 index 56374190c1..c0a27e63d5 100644 --- 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 @@ -1,35 +1,52 @@ --- title: Mine testnet Stacks tokens -description: Set up and run a miner on the Stacks 2.0 testnet -sidebar_position: 4 +description: Set up and run a miner on Stacks Testnet +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 testnet. +For more on the technical details of mining, please review the [mining guide](../stacks-academy/mining) -If you want to learn more about the technical details of mining, please review the [mining guide](../understand-stacks/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)). -## Running bitcoind locally +If you're interested in mining on the Stacks mainnet, you can find instructions on how to do that [here](miner-mainnet): -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) +## Running a Bitcoin Testnet Full Node -First, download the bitcoind software for your platform from https://bitcoin.org/en/download. +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. -Next, start bitcoind with the following configuration: +- [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 -rpcuser=your-bitcoind-username -rpcpassword=your-bitcoind-password testnet=1 -txindex=0 -listen=1 -rpcserialversion=0 -maxorphantx=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 @@ -37,126 +54,51 @@ 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" -... +### Start Bitcoin -[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: +Finally, start bitcoind as follows: ```bash -stacks-node start --config=./testnet/stacks-node/conf/testnet-miner-conf.toml +bitcoind -conf=$HOME/bitcoin.conf ``` -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 -``` +:::note +It will take a few hours for the node to synchronize with Bitcoin testnet. +::: -The above code will compile an optimized binary. To use it, run: +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 -cd ../.. -./target/release/stacks-node start --config=./testnet/conf/testnet-follower-conf.toml +$ bitcoin-cli \ + -rpcconnect=localhost \ + -rpcport=18332 \ + -rpcuser=btcuser \ + -rpcpassword=btcpass \ +getblockchaininfo | jq .blocks +2417570 ``` -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 +## Running a Stacks Blockchain miner -### Prerequisites +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) -Make sure are [running a testnet node](run-a-node) before starting this tutorial. +_There may be some extra requirements to building, [defined here](https://github.com/stacksfoundation/miner-docs/blob/main/prerequisites.md#install-required-packages)_ -### Generate keychain and get testnet tokens in Windows +:::tip It is recommened to use a persistent location for the chainstate, in the steps below we're using `/stacks-blockchain` ::: -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. +### Generate a keychain -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. +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. -Generate a keychain: +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 -npm install --global @stacks/cli -stx make_keychain -t > cli_keychain.json -type cli_keychain.json +npx @stacks/cli make_keychain -t 2>/dev/null | jq -r ``` -After this runs, you'll probably see some installation logs, and at the end you should see some JSON that looks like this: +After this runs, you should see some JSON printed to the screen that looks like this: ```json { @@ -170,107 +112,110 @@ After this runs, you'll probably see some installation logs, and at the end you } ``` -:::tip Check out the [Stacks CLI reference](https://docs.hiro.so/references/stacks-cli) for more details ::: +:::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. -Request BTC from faucet: +### Update the Stacks Blockchain Configuration File -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/). +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`. -### Update configuration file +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. -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). +Next, update the bitcoin configuration: -Update the following properties: +- **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] -... -seed = "replace-with-your-private-key" -local_peer_seed = "replace-with-your-private-key" -... +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] -... -# To mine on Testnet, you need to run bitcoind locally -# Details can be found in above section, 'Running bitcoind locally' +chain = "bitcoin" +mode = "xenon" peer_host = "127.0.0.1" -username = "" -password = "" -... +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 ``` -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 +### Start the Stacks Blockchain -To start your miner, run this in the command line: +To run your miner, run this in the command line: ```bash -stacks-node start --config=testnet/stacks-node/conf/testnet-miner-conf.toml +stacks-node start --config=$HOME/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 +### 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 -set RUST_BACKTRACE=full; -set STACKS_LOG_DEBUG=1; -stacks-node start --config=testnet-miner-conf.toml +STACKS_LOG_DEBUG=1 stacks-node start --config=$HOME/testnet-miner-conf.toml ``` -## Optional: Running with Docker +--- + +## Optional: Running a Stacks Blockchain miner with Docker -Alternatively, you can run the testnet node with Docker. +Alternatively, you can run a Stacks testnet miner with Docker. -:::warning Ensure you have [Docker](https://docs.docker.com/get-docker/) installed on your machine. ::: +:::caution Ensure you have [Docker](https://docs.docker.com/get-docker/) installed ::: -### Generate keychain and get testnet tokens +### Generate a Keychain and Get Some Tokens Generate a keychain: ```bash -docker run -i node:14-alpine npx @stacks/cli make_keychain -t 2>/dev/null +docker run -i node:14-alpine npx @stacks/cli make_keychain 2>/dev/null | jq -r ``` -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 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. -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 Stacks Blockchain Docker Configuration File -Update the following properties: +Use the steps oulined above to create the [configuration file](miner-testnet#update-the-stacks-blockchain-configuration-file) -```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 +### 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 ::: @@ -281,7 +226,8 @@ docker run -d \ --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" \ + -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 \ @@ -294,26 +240,22 @@ You can review the node logs with this command: 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). +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 on your machine: +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 testnet tokens - -Generate a keychain: - -```bash -docker run -i node:14-alpine npx @stacks/cli make_keychain -t 2>/dev/null -``` +### Generate keychain and get some tokens -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/). +Use the steps [outlined above](miner-testnet#generate-a-keychain-and-get-some-tokens) ### Install the chart and run the miner @@ -324,7 +266,7 @@ 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.node.seed="replace-with-your-privateKey-from-generate-keychain-step" \ ``` You can review the node logs with this command: From fc6fcd15559e93454a8d28935a619e2cc723c170 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:42:05 +0100 Subject: [PATCH 0313/1444] New translations stacks-node-configuration.md (Korean) --- .../stacks-node-configuration.md | 158 +++++++++++------- 1 file changed, 101 insertions(+), 57 deletions(-) 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 index 89af343dc6..cd216e7103 100644 --- 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 @@ -1,7 +1,7 @@ --- title: Stacks Node Configuration description: Configuration parameters and options for the stacks-node binary -sidebar_position: 6 +sidebar_position: 4 --- ## Usage @@ -10,97 +10,141 @@ sidebar_position: 6 stacks-node sub-command [--subcommand-option ] ``` -## Subcommands +### 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 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 -### mocknet +## Configuration File Options -Start a node based on a fast local setup emulating a burnchain. Ideal for smart contract development. +The Stacks Blockchain configuration file has multiple sections under which an option may be placed. -Example: +- [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) -```bash -stacks-node mocknet -``` +For reference, several configuration file examples are [available here](https://github.com/stacks-network/stacks-blockchain/tree/master/testnet/stacks-node/conf) -### krypton +- [Example mainnet follower configuration](./stacks-node-configuration#example-mainnet-follower-configuration) -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). +### node -Example: +Contains various configuration options for the stacks-node binary. -```bash -stacks-node krypton -``` +| 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. | -### testnet +### events_observer -Start a node that will join and stream blocks from the public testnet. +:::info This section is _optional_ and not required -Example: +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. -```bash -stacks-node testnet -``` +| 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. | | -### mainnet +### connection_options -Start a node that joins and streams blocks from the public mainnet. +:::info This section is _optional_ and not required. -Example: +However, if this section is added, **all** fields are required ::: -```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. +Specifies configuration options for others connecting to the stacks node. -#### Arguments +| 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 | -**--config**: relative or absolute path to the TOML config file. Required. +### burnchain -Example: +This section contains configuration options pertaining to the blockchain the stacks-node binds to on the backend for proof-of-transfer (BTC). -```bash -stacks-node start --config=/path/to/config.toml -``` +| 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` | -See [Configuration File Options](#configuration-file-options) for more information. +#### Mining -#### version +| 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`. | -Displays information about the current version and the release cycle. +### ustx_balance -Example: +- `mocknet`/`testnet` only -```bash -stacks-node version -``` +This section contains configuration options allocating microSTX per address in the genesis block -#### help +This section can repeat multiple times, but each section can only define a single address. -Displays a help message. +:::info This section is only required for the `testnet` and `mocknet` networks. -Example: +However, if this section is added, **all** fields are required ::: -```bash -stacks-node help -``` +| 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 | -## Configuration File Options +## Example Mainnet Follower Configuration -The TOML configuration file has multiple sections under which an option may be placed. +```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" -To see a list of example configurations, [please see this page](https://github.com/stacks-network/stacks-blockchain/tree/master/testnet/stacks-node/conf). +[burnchain] +chain = "bitcoin" +mode = "mainnet" +peer_host = "localhost" +username = "user" +password = "pass" +rpc_port = 8332 +peer_port = 8333 -### Section: node +[[events_observer]] +endpoint = "localhost:3700" +retry_count = 255 +events_keys = ["*"] +``` -Contains various configuration options pertaining to the stacks-node. -Example: + From 9fe7669e0edd41f7c793e5cda21e7818b9adb9d3 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:42:06 +0100 Subject: [PATCH 0314/1444] New translations accounts.md (Korean) --- .../current/stacks-academy/accounts.md | 215 ++++++++++++++++++ 1 file changed, 215 insertions(+) create mode 100644 i18n/ko/docusaurus-plugin-content-docs/current/stacks-academy/accounts.md diff --git a/i18n/ko/docusaurus-plugin-content-docs/current/stacks-academy/accounts.md b/i18n/ko/docusaurus-plugin-content-docs/current/stacks-academy/accounts.md new file mode 100644 index 0000000000..55d0165def --- /dev/null +++ b/i18n/ko/docusaurus-plugin-content-docs/current/stacks-academy/accounts.md @@ -0,0 +1,215 @@ +--- +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" + } + } + ] +} +``` From 4770e1c7595c3b3b62402d42cada21b61058f82d Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:42:07 +0100 Subject: [PATCH 0315/1444] New translations microblocks.md (Korean) --- .../current/stacks-academy/microblocks.md | 107 ++++++++++++++++++ 1 file changed, 107 insertions(+) create mode 100644 i18n/ko/docusaurus-plugin-content-docs/current/stacks-academy/microblocks.md diff --git a/i18n/ko/docusaurus-plugin-content-docs/current/stacks-academy/microblocks.md b/i18n/ko/docusaurus-plugin-content-docs/current/stacks-academy/microblocks.md new file mode 100644 index 0000000000..9310aa65be --- /dev/null +++ b/i18n/ko/docusaurus-plugin-content-docs/current/stacks-academy/microblocks.md @@ -0,0 +1,107 @@ +--- +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. + +[provides an endpoint]: https://docs.hiro.so/get-started/stacks-blockchain-api#nonce-handling +[microblocks_api]: https://docs.hiro.so/api#tag/Microblocks From 3b06a2e6c040aa60d58df598ac6fdb3087f317b3 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:42:08 +0100 Subject: [PATCH 0316/1444] New translations mining.md (Korean) --- .../current/stacks-academy/mining.md | 84 +++++++++++++++++++ 1 file changed, 84 insertions(+) create mode 100644 i18n/ko/docusaurus-plugin-content-docs/current/stacks-academy/mining.md diff --git a/i18n/ko/docusaurus-plugin-content-docs/current/stacks-academy/mining.md b/i18n/ko/docusaurus-plugin-content-docs/current/stacks-academy/mining.md new file mode 100644 index 0000000000..e6e93e130a --- /dev/null +++ b/i18n/ko/docusaurus-plugin-content-docs/current/stacks-academy/mining.md @@ -0,0 +1,84 @@ +--- +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 From a77c8eb15adfce8c79a40f9151eb555dc1d487ad Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:42:09 +0100 Subject: [PATCH 0317/1444] New translations network.md (Korean) --- .../current/stacks-academy/network.md | 148 ++++++++++++++++++ 1 file changed, 148 insertions(+) create mode 100644 i18n/ko/docusaurus-plugin-content-docs/current/stacks-academy/network.md diff --git a/i18n/ko/docusaurus-plugin-content-docs/current/stacks-academy/network.md b/i18n/ko/docusaurus-plugin-content-docs/current/stacks-academy/network.md new file mode 100644 index 0000000000..a0dc623d97 --- /dev/null +++ b/i18n/ko/docusaurus-plugin-content-docs/current/stacks-academy/network.md @@ -0,0 +1,148 @@ +--- +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 +} +``` From fe0743f6574212953d18e7322b860685881dcd3d Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:42:10 +0100 Subject: [PATCH 0318/1444] New translations stacking.md (Korean) --- .../current/stacks-academy/stacking.md | 151 ++++++++++++++++++ 1 file changed, 151 insertions(+) create mode 100644 i18n/ko/docusaurus-plugin-content-docs/current/stacks-academy/stacking.md diff --git a/i18n/ko/docusaurus-plugin-content-docs/current/stacks-academy/stacking.md b/i18n/ko/docusaurus-plugin-content-docs/current/stacks-academy/stacking.md new file mode 100644 index 0000000000..545f538ecb --- /dev/null +++ b/i18n/ko/docusaurus-plugin-content-docs/current/stacks-academy/stacking.md @@ -0,0 +1,151 @@ +--- +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. 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. + +![](/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 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 (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 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) From c53b03dac89e24fa8b87586d2184539f2b2c558c Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:42:11 +0100 Subject: [PATCH 0319/1444] New translations technical-specs.md (Korean) --- .../current/stacks-academy/technical-specs.md | 79 +++++++++++++++++++ 1 file changed, 79 insertions(+) create mode 100644 i18n/ko/docusaurus-plugin-content-docs/current/stacks-academy/technical-specs.md diff --git a/i18n/ko/docusaurus-plugin-content-docs/current/stacks-academy/technical-specs.md b/i18n/ko/docusaurus-plugin-content-docs/current/stacks-academy/technical-specs.md new file mode 100644 index 0000000000..695f849e1a --- /dev/null +++ b/i18n/ko/docusaurus-plugin-content-docs/current/stacks-academy/technical-specs.md @@ -0,0 +1,79 @@ +--- +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). +- 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 whitepaper v2](https://www.youtube.com/watch?v=Wd-Bfe8Sn-Y). From f9a75743f66026f19b73b39ccbc528c74b859795 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:42:12 +0100 Subject: [PATCH 0320/1444] New translations testnet.md (Korean) --- .../current/stacks-academy/testnet.md | 35 +++++++++++++++++++ 1 file changed, 35 insertions(+) create mode 100644 i18n/ko/docusaurus-plugin-content-docs/current/stacks-academy/testnet.md diff --git a/i18n/ko/docusaurus-plugin-content-docs/current/stacks-academy/testnet.md b/i18n/ko/docusaurus-plugin-content-docs/current/stacks-academy/testnet.md new file mode 100644 index 0000000000..f8b9f03df2 --- /dev/null +++ b/i18n/ko/docusaurus-plugin-content-docs/current/stacks-academy/testnet.md @@ -0,0 +1,35 @@ +--- +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. + +### 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) From 547b98c7c8c05f4401df798377fea5c3b7446e5a Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:42:12 +0100 Subject: [PATCH 0321/1444] New translations transactions.md (Korean) --- .../current/stacks-academy/transactions.md | 40 +++++++++++++++++++ 1 file changed, 40 insertions(+) create mode 100644 i18n/ko/docusaurus-plugin-content-docs/current/stacks-academy/transactions.md diff --git a/i18n/ko/docusaurus-plugin-content-docs/current/stacks-academy/transactions.md b/i18n/ko/docusaurus-plugin-content-docs/current/stacks-academy/transactions.md new file mode 100644 index 0000000000..ba6b18f0f7 --- /dev/null +++ b/i18n/ko/docusaurus-plugin-content-docs/current/stacks-academy/transactions.md @@ -0,0 +1,40 @@ +--- +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). ::: From 8013573f787ef2026f4e7903553fddb2b32120d0 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:42:14 +0100 Subject: [PATCH 0322/1444] New translations language-functions.md (Korean) --- .../current/clarity/language-functions.md | 2031 +++++++++++++++++ 1 file changed, 2031 insertions(+) create mode 100644 i18n/ko/docusaurus-plugin-content-docs/current/clarity/language-functions.md diff --git a/i18n/ko/docusaurus-plugin-content-docs/current/clarity/language-functions.md b/i18n/ko/docusaurus-plugin-content-docs/current/clarity/language-functions.md new file mode 100644 index 0000000000..0325c1ac40 --- /dev/null +++ b/i18n/ko/docusaurus-plugin-content-docs/current/clarity/language-functions.md @@ -0,0 +1,2031 @@ +--- +title: Functions +description: See a detailed list of all functions for the Clarity language. +sidebar_position: 3 +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: + +#### 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-existent\"))))) ;; 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-existent\") ;; 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-existent\" })) ;; 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-existent\" }))) ;; 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-existent\" }))) ;; 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 \"Stacks\" '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 successfully 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_ transferred from another principal, but rather minted. + +If a non-positive amount is provided to mint, this function returns `(err 1)`. Otherwise, on successfully 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_ transferred 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 successfully 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 successfully 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)) +``` From 9d284794e4de9d302a3aaf1ae656b04f6097a2c7 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:42:15 +0100 Subject: [PATCH 0323/1444] New translations language-keywords.md (Korean) --- .../current/clarity/language-keywords.md | 146 ++++++++++++++++++ 1 file changed, 146 insertions(+) create mode 100644 i18n/ko/docusaurus-plugin-content-docs/current/clarity/language-keywords.md diff --git a/i18n/ko/docusaurus-plugin-content-docs/current/clarity/language-keywords.md b/i18n/ko/docusaurus-plugin-content-docs/current/clarity/language-keywords.md new file mode 100644 index 0000000000..1aca5359c3 --- /dev/null +++ b/i18n/ko/docusaurus-plugin-content-docs/current/clarity/language-keywords.md @@ -0,0 +1,146 @@ +--- +title: Keywords +description: See a detailed list of all keywords for the Clarity language. +sidebar_position: 4 +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 +``` From 177bdda662e1267711fbba2079a1044cdf11d60a Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:42:16 +0100 Subject: [PATCH 0324/1444] New translations language-types.md (Korean) --- .../current/clarity/language-types.md | 25 +++++++++++++++++++ 1 file changed, 25 insertions(+) create mode 100644 i18n/ko/docusaurus-plugin-content-docs/current/clarity/language-types.md diff --git a/i18n/ko/docusaurus-plugin-content-docs/current/clarity/language-types.md b/i18n/ko/docusaurus-plugin-content-docs/current/clarity/language-types.md new file mode 100644 index 0000000000..0af4577dc9 --- /dev/null +++ b/i18n/ko/docusaurus-plugin-content-docs/current/clarity/language-types.md @@ -0,0 +1,25 @@ +--- +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. | From 76a500b1b005b83122479b1b37e7abfb97dfccab Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:42:18 +0100 Subject: [PATCH 0325/1444] New translations miner-costs-and-fees.md (Korean) --- .../current/nodes-and-miners/miner-costs-and-fees.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) 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 index 40397a51e0..dd8ee721cc 100644 --- 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 @@ -8,7 +8,7 @@ sidebar_position: 8 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 @@ -22,3 +22,5 @@ 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). From 39dc86115d831e8607f2ea83cb71cec80647543b Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:42:19 +0100 Subject: [PATCH 0326/1444] New translations verify-miner.md (Korean) --- .../current/nodes-and-miners/verify-miner.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) 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 index 094e3f03a1..18e8dd3a48 100644 --- 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 @@ -7,7 +7,7 @@ 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 +$ 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 -``` \ No newline at end of file +``` From dfb4710c47d0073f9249638a1470226ad131bc0f Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:42:19 +0100 Subject: [PATCH 0327/1444] New translations stacks-blockchain-api.md (Korean) --- .../stacks-academy/stacks-blockchain-api.md | 41 +++++++++++++++++++ 1 file changed, 41 insertions(+) create mode 100644 i18n/ko/docusaurus-plugin-content-docs/current/stacks-academy/stacks-blockchain-api.md diff --git a/i18n/ko/docusaurus-plugin-content-docs/current/stacks-academy/stacks-blockchain-api.md b/i18n/ko/docusaurus-plugin-content-docs/current/stacks-academy/stacks-blockchain-api.md new file mode 100644 index 0000000000..ad9bb1822e --- /dev/null +++ b/i18n/ko/docusaurus-plugin-content-docs/current/stacks-academy/stacks-blockchain-api.md @@ -0,0 +1,41 @@ +--- +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`. ::: From fa02690a8c27d320e29147e1345e7410211f6d50 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:42:21 +0100 Subject: [PATCH 0328/1444] New translations run-a-node.md (Korean) --- .../current/nodes-and-miners/run-a-node.md | 329 +++--------------- 1 file changed, 42 insertions(+), 287 deletions(-) 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 index 94d938c5ca..2993568ce4 100644 --- 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 @@ -1,5 +1,5 @@ --- -title: Run a node +title: Run a Node with Docker description: Set up and run a Stacks node sidebar_position: 1 tags: @@ -8,344 +8,99 @@ tags: ## Stacks Blockchain with Docker -Run your own Stacks Blockchain node easily with just few commands. +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) -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](./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) -## **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 -``` +## **Requirements:** -- With optional proxy: +The **minimum viable requirements** are listed below. -```bash -./manage.sh -n -a start -f proxy -``` +While you _can_ run a node using these specs, it's _recommended_ to assign more than the minimum for better performance. -- With optional bitcoin node: +- ⚠️ [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_ ) -```bash -./manage.sh -n -a start -f bitcoin -``` +:::caution MacOS with an ARM processor is NOT recommended -5. **Stop the Services** +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. ::: -```bash -./manage.sh -n -a stop -``` - -6. **Retrieve Service Logs** - -```bash -./manage.sh -n -a logs -``` - -- Export docker log files to `./exported-logs`: +## **Quickstart** -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. +The `` placeholder used below can be replaced with one of: -```bash -./manage.sh -n -a logs export -``` +- mainnet +- testnet +- mocknet -7. **Restart all services** +1. **Clone the stacks-blockchain-docker repository locally** ```bash -./manage.sh -n -a restart +git clone https://github.com/stacks-network/stacks-blockchain-docker && cd stacks-blockchain-docker ``` -- With optional proxy: +2. **Start the Services** ```bash -./manage.sh -n -a restart -f proxy +./manage.sh -n -a start ``` -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. +:::note With an optional HTTP proxy on port 80: ```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. - +./manage.sh -n -a start -f proxy ``` -9. **Download BNS data to** `./persistent-data/bns-data` - -```bash -./manage.sh bns -``` +::: -10. **Export stacks-blockchain-api events** (_Not applicable for mocknet_) +## **Accessing the services** -```bash -./manage.sh -n -a export -# check logs for completion -./manage.sh -n -a restart -``` +:::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. -11. **Replay stacks-blockchain-api events** (_Not applicable for mocknet_) +Follow the logs to track the sync progress: ```bash -./manage.sh -n -a import -# check logs for completion -./manage.sh -n -a restart +./manage.sh -n -a logs ``` -## **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` +- Ports `20443-20444` are exposed on `localhost` ```bash -curl -sL localhost:20443/v2/info | jq +curl -sL localhost:20443/v2/info | jq -r ``` **stacks-blockchain-api**: -- Port `3999` are exposed to `localhost` +- Port `3999` is exposed on `localhost` ```bash -curl -sL localhost:3999/v2/info | jq +curl -sL localhost:3999 | jq -r ``` **proxy**: -- Port `80` is exposed to `localhost` +- Port `80` is exposed on `localhost` ```bash -curl -sL localhost/v2/info | jq -curl -sL localhost/ | jq +curl -sL localhost/v2/info | jq -r +curl -sL localhost | jq -r ``` --- ## 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 -``` +:::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): ::: --- - -## **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 From 5c6f4cd46f1c564183ad8997499f49574fba5db8 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:42:21 +0100 Subject: [PATCH 0329/1444] New translations index.md (Korean) --- .../current/clarity/index.md | 58 +++++++++++++++++++ 1 file changed, 58 insertions(+) create mode 100644 i18n/ko/docusaurus-plugin-content-docs/current/clarity/index.md diff --git a/i18n/ko/docusaurus-plugin-content-docs/current/clarity/index.md b/i18n/ko/docusaurus-plugin-content-docs/current/clarity/index.md new file mode 100644 index 0000000000..903de93a45 --- /dev/null +++ b/i18n/ko/docusaurus-plugin-content-docs/current/clarity/index.md @@ -0,0 +1,58 @@ +--- +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?2 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. If you are unsure what this means, let it not worry you for now. The serious advantage of decidability will become more apparent over time. + +### 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. From e1930e75954e2115543ab403b1cce1e200662408 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:42:22 +0100 Subject: [PATCH 0330/1444] New translations index.md (Korean) --- .../current/stacks-academy/index.md | 11 +++++++++++ 1 file changed, 11 insertions(+) create mode 100644 i18n/ko/docusaurus-plugin-content-docs/current/stacks-academy/index.md diff --git a/i18n/ko/docusaurus-plugin-content-docs/current/stacks-academy/index.md b/i18n/ko/docusaurus-plugin-content-docs/current/stacks-academy/index.md new file mode 100644 index 0000000000..a5bdb3c790 --- /dev/null +++ b/i18n/ko/docusaurus-plugin-content-docs/current/stacks-academy/index.md @@ -0,0 +1,11 @@ +--- +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. From aaf4d7f44bc171e6ae99e8bddc9768c223db9682 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:42:23 +0100 Subject: [PATCH 0331/1444] New translations proof-of-transfer.md (Korean) --- .../stacks-academy/proof-of-transfer.md | 83 +++++++++++++++++++ 1 file changed, 83 insertions(+) create mode 100644 i18n/ko/docusaurus-plugin-content-docs/current/stacks-academy/proof-of-transfer.md diff --git a/i18n/ko/docusaurus-plugin-content-docs/current/stacks-academy/proof-of-transfer.md b/i18n/ko/docusaurus-plugin-content-docs/current/stacks-academy/proof-of-transfer.md new file mode 100644 index 0000000000..50f4b739d6 --- /dev/null +++ b/i18n/ko/docusaurus-plugin-content-docs/current/stacks-academy/proof-of-transfer.md @@ -0,0 +1,83 @@ +--- +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. From d6e54d3330ffa450e5646c3a752297812d5c21c4 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:42:24 +0100 Subject: [PATCH 0332/1444] New translations what-is-stacks.md (Korean) --- .../current/stacks-academy/what-is-stacks.md | 102 ++++++++++++++++++ 1 file changed, 102 insertions(+) create mode 100644 i18n/ko/docusaurus-plugin-content-docs/current/stacks-academy/what-is-stacks.md diff --git a/i18n/ko/docusaurus-plugin-content-docs/current/stacks-academy/what-is-stacks.md b/i18n/ko/docusaurus-plugin-content-docs/current/stacks-academy/what-is-stacks.md new file mode 100644 index 0000000000..94277da8a9 --- /dev/null +++ b/i18n/ko/docusaurus-plugin-content-docs/current/stacks-academy/what-is-stacks.md @@ -0,0 +1,102 @@ +--- +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. + +There's a lot of jargon, possible assumptions, controversy, and cool technology wrapped up in those statements. So let's get started by getting a 30,000 foot view of what exactly Stacks is. + +## Stacks Explained in (Slightly Less Than) 10 Minutes + +
+ +
+ +## 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, Stacks takes a different approach. + +## 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). + +By taking this 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 with some unique properties, like having its own token, that allow it to maintain a historical ledger of all of its transactions and operate with its own security budget. + +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_. + +Nope. 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. From 0aeaf4d90070ebec18568420d17ba386033002f1 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:42:25 +0100 Subject: [PATCH 0333/1444] New translations community-tutorials.md (Korean) --- .../current/tutorials/community-tutorials.md | 24 +++++++++++++++++++ 1 file changed, 24 insertions(+) create mode 100644 i18n/ko/docusaurus-plugin-content-docs/current/tutorials/community-tutorials.md diff --git a/i18n/ko/docusaurus-plugin-content-docs/current/tutorials/community-tutorials.md b/i18n/ko/docusaurus-plugin-content-docs/current/tutorials/community-tutorials.md new file mode 100644 index 0000000000..a4f3d970ca --- /dev/null +++ b/i18n/ko/docusaurus-plugin-content-docs/current/tutorials/community-tutorials.md @@ -0,0 +1,24 @@ +--- +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/) From 05135edbb53a13025019a296047fbe76970ab88a Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:42:26 +0100 Subject: [PATCH 0334/1444] New translations hello-stacks.md (Korean) --- .../current/tutorials/hello-stacks.md | 759 ++++++++++++++++++ 1 file changed, 759 insertions(+) create mode 100644 i18n/ko/docusaurus-plugin-content-docs/current/tutorials/hello-stacks.md diff --git a/i18n/ko/docusaurus-plugin-content-docs/current/tutorials/hello-stacks.md b/i18n/ko/docusaurus-plugin-content-docs/current/tutorials/hello-stacks.md new file mode 100644 index 0000000000..a0a442d135 --- /dev/null +++ b/i18n/ko/docusaurus-plugin-content-docs/current/tutorials/hello-stacks.md @@ -0,0 +1,759 @@ +--- +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. From 29868cd0bc1afb3915365d226c55dd35da2eee2b Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:42:26 +0100 Subject: [PATCH 0335/1444] New translations index.md (Korean) --- .../current/tutorials/index.md | 11 +++++++++++ 1 file changed, 11 insertions(+) create mode 100644 i18n/ko/docusaurus-plugin-content-docs/current/tutorials/index.md diff --git a/i18n/ko/docusaurus-plugin-content-docs/current/tutorials/index.md b/i18n/ko/docusaurus-plugin-content-docs/current/tutorials/index.md new file mode 100644 index 0000000000..1d544c7bc1 --- /dev/null +++ b/i18n/ko/docusaurus-plugin-content-docs/current/tutorials/index.md @@ -0,0 +1,11 @@ +--- +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. From 19ce3b86c3b84814529c86244b002dfe39b30810 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:42:27 +0100 Subject: [PATCH 0336/1444] New translations satoshis-ridge.md (Korean) --- .../current/tutorials/satoshis-ridge.md | 75 +++++++++++++++++++ 1 file changed, 75 insertions(+) create mode 100644 i18n/ko/docusaurus-plugin-content-docs/current/tutorials/satoshis-ridge.md diff --git a/i18n/ko/docusaurus-plugin-content-docs/current/tutorials/satoshis-ridge.md b/i18n/ko/docusaurus-plugin-content-docs/current/tutorials/satoshis-ridge.md new file mode 100644 index 0000000000..596339ae74 --- /dev/null +++ b/i18n/ko/docusaurus-plugin-content-docs/current/tutorials/satoshis-ridge.md @@ -0,0 +1,75 @@ +--- +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 arguable one of its strengths. + +Instead, we need to create separate layers that add additional functionality without modify 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. From 663c719a0f6a930a2dc20fc919dc6504519fb8a0 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:42:28 +0100 Subject: [PATCH 0337/1444] New translations crash-course.md (Korean) --- .../current/clarity/crash-course.md | 122 ++++++++++++++++++ 1 file changed, 122 insertions(+) create mode 100644 i18n/ko/docusaurus-plugin-content-docs/current/clarity/crash-course.md diff --git a/i18n/ko/docusaurus-plugin-content-docs/current/clarity/crash-course.md b/i18n/ko/docusaurus-plugin-content-docs/current/clarity/crash-course.md new file mode 100644 index 0000000000..5b27a3c275 --- /dev/null +++ b/i18n/ko/docusaurus-plugin-content-docs/current/clarity/crash-course.md @@ -0,0 +1,122 @@ +--- +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.md). + +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. + +```clojure +(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: + +```clojure +(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. From f642567a270b2999f9218c35287dda5cccbe9faa Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:42:29 +0100 Subject: [PATCH 0338/1444] New translations sample-contracts.md (Korean) --- .../current/clarity/sample-contracts.md | 14 ++++++++++++++ 1 file changed, 14 insertions(+) create mode 100644 i18n/ko/docusaurus-plugin-content-docs/current/clarity/sample-contracts.md diff --git a/i18n/ko/docusaurus-plugin-content-docs/current/clarity/sample-contracts.md b/i18n/ko/docusaurus-plugin-content-docs/current/clarity/sample-contracts.md new file mode 100644 index 0000000000..adb12a58fd --- /dev/null +++ b/i18n/ko/docusaurus-plugin-content-docs/current/clarity/sample-contracts.md @@ -0,0 +1,14 @@ +--- +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) From c4e61a94f04f99f98f9705c9f29339d82f016d8c Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:42:30 +0100 Subject: [PATCH 0339/1444] New translations index.md (Korean) --- .../current/cookbook/index.md | 64 +++++++++++++++++++ 1 file changed, 64 insertions(+) create mode 100644 i18n/ko/docusaurus-plugin-content-docs/current/cookbook/index.md diff --git a/i18n/ko/docusaurus-plugin-content-docs/current/cookbook/index.md b/i18n/ko/docusaurus-plugin-content-docs/current/cookbook/index.md new file mode 100644 index 0000000000..a2b0e42eea --- /dev/null +++ b/i18n/ko/docusaurus-plugin-content-docs/current/cookbook/index.md @@ -0,0 +1,64 @@ +--- +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 + +Swapping between Bitcoin and Stacks addresses + +Swapping between xBTC and BTC + +Verifying a transaction on the BTC chain + +## 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 + +Airdropping an NFT to a Bitcoin address + +## Stacking and Mining + +Simple stacking pool + +Continuous stacking + +Simple mining pool + +Proof of PoX payout + +## Oracles + +Creating a simple BTC price oracle + +## Frontend + +[Post conditions with Stacks.js](./post-conditions) + +[Authentication with Stacks.js](./stacks-js-auth) + +[Sending transactions with Stacks.js](./stacks-js-sending-transactions) + +## Complete Apps + +[Sup](https://github.com/kenrogers/sup) + +[Hello Stacks](https://github.com/kenrogers/hello-stacks) From e4ed643413a3a0dee0af88645315e989b6680853 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:42:31 +0100 Subject: [PATCH 0340/1444] New translations btc-connection.md (Korean) --- .../current/stacks-academy/btc-connection.md | 196 ++++++++++++++++++ 1 file changed, 196 insertions(+) create mode 100644 i18n/ko/docusaurus-plugin-content-docs/current/stacks-academy/btc-connection.md diff --git a/i18n/ko/docusaurus-plugin-content-docs/current/stacks-academy/btc-connection.md b/i18n/ko/docusaurus-plugin-content-docs/current/stacks-academy/btc-connection.md new file mode 100644 index 0000000000..b4db915969 --- /dev/null +++ b/i18n/ko/docusaurus-plugin-content-docs/current/stacks-academy/btc-connection.md @@ -0,0 +1,196 @@ +--- +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. + +## Stacks Among Other Bitcoin Layers + +In the [last section](./what-is-stacks.md) we covered what Stacks actually is and what problem it is solving, but this is not a new problem. The Bitcoin write problem has been a bit of a holy grail problem in the crypto world for a while now. + +Bitcoin is the OG cryptocurrency and has the largest market cap, but it also some of the least functionality, which means if we want to make it a productive asset and use it to build a decentralized economy, we need to take a layered approach and let Bitcoin do what it does best, while creating additional layers on top of it to add functionality. + +So how does Stacks compare to some of the other approaches to layering on top of Bitcoin? + +### 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. + +## 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. + +But because it has its own execution environment and smart contract state to maintain, it needs a token to incentivize maintenance of the network. + +But it goes further than that. It is possible to build a system like this without a token using something like merge-mining or a sidechain, but then we lose out on the additional benefit of having the chain state's safety underpinned by its entire token economy's value. + +In the case of Stacks, the safety and liveness of the chain are underpinned by this value, and the stacking mechanism incentivizes network members to increase this value. + +From Jude Nelson, Stacks core developer: + +"How hard is it to cause a safety failure (i.e. a double-spend via a reorg) on just the canonical Stacks chain fork? Anyone can become a miner by spending BTC, so without loss of generality, reverting the last block on the canonical chain is at least as hard in expectation as spending more BTC than the rest of the miners combined for that block. Because each Bitcoin block selects at most one Stacks block, the act of reorging the canonical Stacks chain back N blocks is the act of winning at least N + 1 blocks built off of a common ancestor that is N blocks deep. This is a lower bound on the number of Bitcoin blocks mined during which a reorg needs to take place — in practice, honest miners will keep working on the canonical chain, and will win some Stacks blocks of their own, which in turn increases the number of Stacks blocks the reorging miners must win. + +How costly is it to carry out a reorg of N blocks? It’s a function of how valuable STX is relative to BTC — the more valuable STX are, the more BTC honest miners are committing to mining (this has borne out in practice), and thus the more BTC a reorging miner must commit. Therefore, the cost of a reorg is a function of the value of STX. + +This is similar to the economic security of a PoW blockchain. Like in PoW, each fork of the Stacks chain has its own independent “security budget” — an attacker must out-spend the security budget to carry out a reorg, and the security budget is a function of the block rewards. In PoX, the only difference is that the miners spend another blockchain’s tokens (BTC in Stacks’ case) instead of energy. Therefore, Stacks can’t be a sidechain, a drivechain, or a merge-mined chain, because none of these other systems’ security budgets are a function of their tokens’ worth. Sidechains, drivechains, and merged-mined chains all rely on external miners for their safety, since their safety is guaranteed in part by external miners validating their blocks. The onus on these systems is to get external miners to care enough to do so, and in the case of sidechains, drivechains, and blind merged-mined chains, there is an additional onus to encourage their nodes to mine blocks at all (since there is no on-chain reward for them to earn by doing so). By contrast, disinterested Bitcoin miners neither assist nor prevent a reorg in PoX — they only record the history of all Stacks forks. + +PoX offers two additional, unique security properties on top of PoW. First, no matter how much BTC a reorging miner can commit, the act of executing a reorg is going to be time-consuming. Unless the attacker can attack the Bitcoin chain itself by quickly producing a better Bitcoin fork, a reorging miner must sustain the attack for at least N + 1 Bitcoin blocks. This gives honest miners and users ample time to notice and react to the reorg attempt. + +Second, the history of block production in all Stacks forks is embedded within Bitcoin. This allows the system to leverage Bitcoin’s security budget in order to ensure that all forks are public. This is because the act of producing a hidden Stacks fork, where the fork’s block hashes are not known to the honest miners, is the act of producing a hidden canonical Bitcoin fork. Therefore, the act of producing a hidden Stacks fork is at least as hard as reorging the Bitcoin chain. A PoX chain leverages this property not to prevent reorgs, but to make reorgs unprofitable. + +By anchoring blocks to an existing blockchain, a PoX chain forces reorgs to happen out in the open, thereby giving advance warning to all honest network participants when they happen. Honest miners, users, and exchanges will see the PoX transactions for reorg attempts on the existing blockchain, and adapt their behaviors accordingly: honest miners will increase their commitments, and users and exchanges will require more confirmations for transactions. This makes the act of carrying out a reorg while also making a profit much more challenging, since malicious reorgs — like selfish mining and double-spending — rely on secrecy to work effectively. Specific to Stacks, miners are additionally required to mine for a “warm-up” period of two blocks, during which they must spend BTC at their target commit levels but will not win any Stacks blocks. So, a high-budget reorg attempt will not only be costly, but will also alert the rest of the network before the damage is done." + +- [What Kind of Blockchain is Stacks?](https://stacks.org/stacks-blockchain) + +## 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) From c1d1f2b35214f900fdb705679b6a3ae8f4b1c411 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:42:31 +0100 Subject: [PATCH 0341/1444] New translations post-conditions.md (Korean) --- .../current/stacks-academy/post-conditions.md | 39 +++++++++++++++++++ 1 file changed, 39 insertions(+) create mode 100644 i18n/ko/docusaurus-plugin-content-docs/current/stacks-academy/post-conditions.md diff --git a/i18n/ko/docusaurus-plugin-content-docs/current/stacks-academy/post-conditions.md b/i18n/ko/docusaurus-plugin-content-docs/current/stacks-academy/post-conditions.md new file mode 100644 index 0000000000..bb0727194f --- /dev/null +++ b/i18n/ko/docusaurus-plugin-content-docs/current/stacks-academy/post-conditions.md @@ -0,0 +1,39 @@ +--- +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). From e776f46b7177a374427e97c1e641dce55843f456 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:42:32 +0100 Subject: [PATCH 0342/1444] New translations creating-an-ft.md (Korean) --- .../current/cookbook/creating-an-ft.md | 99 +++++++++++++++++++ 1 file changed, 99 insertions(+) create mode 100644 i18n/ko/docusaurus-plugin-content-docs/current/cookbook/creating-an-ft.md diff --git a/i18n/ko/docusaurus-plugin-content-docs/current/cookbook/creating-an-ft.md b/i18n/ko/docusaurus-plugin-content-docs/current/cookbook/creating-an-ft.md new file mode 100644 index 0000000000..4e3bad99d2 --- /dev/null +++ b/i18n/ko/docusaurus-plugin-content-docs/current/cookbook/creating-an-ft.md @@ -0,0 +1,99 @@ +--- +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) + ) +) +``` From 08debb585c598447fd5b43c1cc25d22dbd9ae1a3 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:42:33 +0100 Subject: [PATCH 0343/1444] New translations creating-an-nft.md (Korean) --- .../current/cookbook/creating-an-nft.md | 87 +++++++++++++++++++ 1 file changed, 87 insertions(+) create mode 100644 i18n/ko/docusaurus-plugin-content-docs/current/cookbook/creating-an-nft.md diff --git a/i18n/ko/docusaurus-plugin-content-docs/current/cookbook/creating-an-nft.md b/i18n/ko/docusaurus-plugin-content-docs/current/cookbook/creating-an-nft.md new file mode 100644 index 0000000000..08faf9393a --- /dev/null +++ b/i18n/ko/docusaurus-plugin-content-docs/current/cookbook/creating-an-nft.md @@ -0,0 +1,87 @@ +--- +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 +Code for this recipe has been pulled from [this NFT tutorial](https://blog.developerdao.com/building-an-nft-with-stacks-and-clarity) from Developer DAO. +::: + +## 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) + ) +) +``` From aee349b60c252e0a98a48cedb5b31e636269137e Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:42:34 +0100 Subject: [PATCH 0344/1444] New translations post-conditions.md (Korean) --- .../current/cookbook/post-conditions.md | 136 ++++++++++++++++++ 1 file changed, 136 insertions(+) create mode 100644 i18n/ko/docusaurus-plugin-content-docs/current/cookbook/post-conditions.md diff --git a/i18n/ko/docusaurus-plugin-content-docs/current/cookbook/post-conditions.md b/i18n/ko/docusaurus-plugin-content-docs/current/cookbook/post-conditions.md new file mode 100644 index 0000000000..571fc20d48 --- /dev/null +++ b/i18n/ko/docusaurus-plugin-content-docs/current/cookbook/post-conditions.md @@ -0,0 +1,136 @@ +--- +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. From 860182cf1ddeea9c53f528325482b4a4cbf148c4 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:42:35 +0100 Subject: [PATCH 0345/1444] New translations stacks-js-auth.md (Korean) --- .../current/cookbook/stacks-js-auth.md | 98 +++++++++++++++++++ 1 file changed, 98 insertions(+) create mode 100644 i18n/ko/docusaurus-plugin-content-docs/current/cookbook/stacks-js-auth.md diff --git a/i18n/ko/docusaurus-plugin-content-docs/current/cookbook/stacks-js-auth.md b/i18n/ko/docusaurus-plugin-content-docs/current/cookbook/stacks-js-auth.md new file mode 100644 index 0000000000..89d1f06e00 --- /dev/null +++ b/i18n/ko/docusaurus-plugin-content-docs/current/cookbook/stacks-js-auth.md @@ -0,0 +1,98 @@ +--- +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 && ( + + ); +} +``` From b9e4356a3253cb335ef04b352837d009a21c7568 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:42:36 +0100 Subject: [PATCH 0346/1444] New translations stacks-js-sending-transactions.md (Korean) --- .../stacks-js-sending-transactions.md | 55 +++++++++++++++++++ 1 file changed, 55 insertions(+) create mode 100644 i18n/ko/docusaurus-plugin-content-docs/current/cookbook/stacks-js-sending-transactions.md diff --git a/i18n/ko/docusaurus-plugin-content-docs/current/cookbook/stacks-js-sending-transactions.md b/i18n/ko/docusaurus-plugin-content-docs/current/cookbook/stacks-js-sending-transactions.md new file mode 100644 index 0000000000..849c7d1f42 --- /dev/null +++ b/i18n/ko/docusaurus-plugin-content-docs/current/cookbook/stacks-js-sending-transactions.md @@ -0,0 +1,55 @@ +--- +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. From db3d25f5bc89c228b786ac9115fa66d69f41252e Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:42:36 +0100 Subject: [PATCH 0347/1444] New translations _category_.json (Korean) --- .../current/clarity/noteworthy-contracts/_category_.json | 8 ++++++++ 1 file changed, 8 insertions(+) create mode 100644 i18n/ko/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/_category_.json diff --git a/i18n/ko/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/_category_.json b/i18n/ko/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/_category_.json new file mode 100644 index 0000000000..f5de305558 --- /dev/null +++ b/i18n/ko/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/_category_.json @@ -0,0 +1,8 @@ +{ + "label": "Noteworthy Contracts", + "position": 4, + "link": { + "type": "generated-index", + "description": "Specific deployed Clarity Contracts worth mentioning." + } +} \ No newline at end of file From fd2337a56cb314ea2158ff8fb6732673fda0e388 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:42:37 +0100 Subject: [PATCH 0348/1444] New translations bns-contract.md (Korean) --- .../noteworthy-contracts/bns-contract.md | 519 ++++++++++++++++++ 1 file changed, 519 insertions(+) create mode 100644 i18n/ko/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/bns-contract.md diff --git a/i18n/ko/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/bns-contract.md b/i18n/ko/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/bns-contract.md new file mode 100644 index 0000000000..a7770b7d24 --- /dev/null +++ b/i18n/ko/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/bns-contract.md @@ -0,0 +1,519 @@ +--- +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 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` From e6e42f3a932ac5f212bfbb56834ec8271ed7a047 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:42:38 +0100 Subject: [PATCH 0349/1444] New translations xbtc.md (Korean) --- .../clarity/noteworthy-contracts/xbtc.md | 28 +++++++++++++++++++ 1 file changed, 28 insertions(+) create mode 100644 i18n/ko/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/xbtc.md diff --git a/i18n/ko/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/xbtc.md b/i18n/ko/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/xbtc.md new file mode 100644 index 0000000000..e535dcf260 --- /dev/null +++ b/i18n/ko/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/xbtc.md @@ -0,0 +1,28 @@ +--- +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) From 24b39c55be30d74d6098e09edb4ad90da271a340 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:42:39 +0100 Subject: [PATCH 0350/1444] New translations index.md (Korean) --- .../current/glossary/index.md | 284 ++++++++++++++++++ 1 file changed, 284 insertions(+) create mode 100644 i18n/ko/docusaurus-plugin-content-docs/current/glossary/index.md diff --git a/i18n/ko/docusaurus-plugin-content-docs/current/glossary/index.md b/i18n/ko/docusaurus-plugin-content-docs/current/glossary/index.md new file mode 100644 index 0000000000..419c0e0d73 --- /dev/null +++ b/i18n/ko/docusaurus-plugin-content-docs/current/glossary/index.md @@ -0,0 +1,284 @@ +--- +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. From a80412d300b089564403a1154fb1aea8cff15948 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:42:40 +0100 Subject: [PATCH 0351/1444] New translations quicknode.md (Korean) --- .../current/nodes-and-miners/quicknode.md | 45 +++++++++++++++++++ 1 file changed, 45 insertions(+) create mode 100644 i18n/ko/docusaurus-plugin-content-docs/current/nodes-and-miners/quicknode.md diff --git a/i18n/ko/docusaurus-plugin-content-docs/current/nodes-and-miners/quicknode.md b/i18n/ko/docusaurus-plugin-content-docs/current/nodes-and-miners/quicknode.md new file mode 100644 index 0000000000..1281964689 --- /dev/null +++ b/i18n/ko/docusaurus-plugin-content-docs/current/nodes-and-miners/quicknode.md @@ -0,0 +1,45 @@ +--- +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. From db625b3dfd053cca7ac5ea1bb879c0806f3bb4cf Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:42:41 +0100 Subject: [PATCH 0352/1444] New translations defi.md (Korean) --- .../current/services-using-stacks/defi.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) 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 index 51defacba7..58717a3234 100644 --- 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 @@ -26,7 +26,7 @@ Please edit this page to add any relevant new site that we are missing. ## Lnswap -[LNSWAP](https://www.lnswap.org). Non custiodial crypto currency exchange +[LNSWAP](https://www.lnswap.org). Non-custodial crypto currency exchange ![](/img/sh_lnswap.png) @@ -41,4 +41,3 @@ Please edit this page to add any relevant new site that we are missing. [Stackswap](https://app.stackswap.org/v2) ![](/img/sh_stackswap.png) - From 7db7e635cc15d08e30cc9cef938728c7be7b2585 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:42:42 +0100 Subject: [PATCH 0353/1444] New translations more.md (Korean) --- .../current/services-using-stacks/more.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) 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 index df0b3e2254..1e14b9a5a5 100644 --- 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 @@ -18,6 +18,6 @@ Please edit this page to add any relevant new site that we are missing. ## Sigle -[Sigle](https://www.sigle.io/) is a decentralised and open source web 3 writing platform. +[Sigle](https://www.sigle.io/) is a decentralized and open source web 3 writing platform. -![](/img/sh_sigle.png) \ No newline at end of file +![](/img/sh_sigle.png) From 65f7d73458a717905e1ca864d58dd2cdd14c4074 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:42:42 +0100 Subject: [PATCH 0354/1444] New translations nft.md (Korean) --- .../current/services-using-stacks/nft.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) 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 index abb770663c..d582604854 100644 --- 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 @@ -15,6 +15,7 @@ Please edit this page to add any relevant new site that we are missing. ![website-screenshot](/img/sh_nft_byzantion.png) ### [Gamma](https://gamma.io/) + ![website-screenshot](/img/sh_nft_gamma.png) ### [Megapont](https://www.megapont.com/) @@ -35,4 +36,4 @@ Please edit this page to add any relevant new site that we are missing. ### [Superfandom](https://superfandom.io/) -![website-screenshot](/img/sh_superfandom.png) \ No newline at end of file +![website-screenshot](/img/sh_superfandom.png) From d23a8467c50c12066845fbaf42094dd62bac0fd2 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:42:43 +0100 Subject: [PATCH 0355/1444] New translations stacks-info-sites.md (Korean) --- .../current/services-using-stacks/stacks-info-sites.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) 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 index 35ced8dac6..54f6823e33 100644 --- 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 @@ -30,7 +30,7 @@ Please edit this page to add any relevant new site that we are missing. ![website-screenshot](/img/sh_stxstats.png) -### [Novuminsights](https://stacks.novuminsights.com/health) +### [Novum Insights](https://stacks.novuminsights.com/health) ![website-screenshot](/img/sh_novuminsights.png) From 8aab4bff144cb9de21124edb64b0979b940c1902 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:42:44 +0100 Subject: [PATCH 0356/1444] New translations wallets.md (Korean) --- .../current/services-using-stacks/wallets.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) 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 index e5ea6c5b45..2d3fcc85f2 100644 --- 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 @@ -15,6 +15,7 @@ Please edit this page to add any relevant new site that we are missing. [Blockchain.com](https://www.blockchain.com/wallet) ![](/img/sh_blockchain.png) + ## Boom [Boom](https://boom.money) @@ -26,6 +27,7 @@ Please edit this page to add any relevant new site that we are missing. [D'CENT](https://dcentwallet.com) ![](/img/sh_dcent.png) + ## Hiro Wallet [Hiro Wallet](https://www.hiro.so/wallet) @@ -48,4 +50,4 @@ Please edit this page to add any relevant new site that we are missing. [Wise](https://wiseapp.id) -![](/img/sh_wiseapp.png) \ No newline at end of file +![](/img/sh_wiseapp.png) From c19cabda5f19b4f37592e7f8701f23a966745796 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:42:45 +0100 Subject: [PATCH 0357/1444] New translations whitepapers.md (Korean) --- .../current/stacks-academy/whitepapers.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) create mode 100644 i18n/ko/docusaurus-plugin-content-docs/current/stacks-academy/whitepapers.md diff --git a/i18n/ko/docusaurus-plugin-content-docs/current/stacks-academy/whitepapers.md b/i18n/ko/docusaurus-plugin-content-docs/current/stacks-academy/whitepapers.md new file mode 100644 index 0000000000..0e564fbf44 --- /dev/null +++ b/i18n/ko/docusaurus-plugin-content-docs/current/stacks-academy/whitepapers.md @@ -0,0 +1,12 @@ +--- +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) From fe2cc5757b997ae6340b5c89cd0b61aa25d711f3 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:42:46 +0100 Subject: [PATCH 0358/1444] New translations stacking-contract.md (Korean) --- .../noteworthy-contracts/stacking-contract.md | 352 ++++++++++++++++++ 1 file changed, 352 insertions(+) create mode 100644 i18n/ko/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/stacking-contract.md diff --git a/i18n/ko/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/stacking-contract.md b/i18n/ko/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/stacking-contract.md new file mode 100644 index 0000000000..c0027256cd --- /dev/null +++ b/i18n/ko/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/stacking-contract.md @@ -0,0 +1,352 @@ +--- +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. 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` From 57c7fbb9c4b2cb83f3754cd5687231872a55570e Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:42:47 +0100 Subject: [PATCH 0359/1444] New translations index.md (Korean) --- .../current/next-steps/index.md | 39 +++++++++++++++++++ 1 file changed, 39 insertions(+) create mode 100644 i18n/ko/docusaurus-plugin-content-docs/current/next-steps/index.md diff --git a/i18n/ko/docusaurus-plugin-content-docs/current/next-steps/index.md b/i18n/ko/docusaurus-plugin-content-docs/current/next-steps/index.md new file mode 100644 index 0000000000..00ddec9178 --- /dev/null +++ b/i18n/ko/docusaurus-plugin-content-docs/current/next-steps/index.md @@ -0,0 +1,39 @@ +--- +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) From 99ae5e34ae2c165804783a7daf9e9e19d25e6809 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:42:48 +0100 Subject: [PATCH 0360/1444] New translations sips.md (Korean) --- .../current/stacks-academy/sips.md | 52 +++++++++++++++++++ 1 file changed, 52 insertions(+) create mode 100644 i18n/ko/docusaurus-plugin-content-docs/current/stacks-academy/sips.md diff --git a/i18n/ko/docusaurus-plugin-content-docs/current/stacks-academy/sips.md b/i18n/ko/docusaurus-plugin-content-docs/current/stacks-academy/sips.md new file mode 100644 index 0000000000..aa2db18e62 --- /dev/null +++ b/i18n/ko/docusaurus-plugin-content-docs/current/stacks-academy/sips.md @@ -0,0 +1,52 @@ +--- +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/IJ15791776) 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-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. From 030c8a02682ee698d08aa2c52aac1e1c2a31713f Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:42:48 +0100 Subject: [PATCH 0361/1444] New translations hosted-nodes.md (Korean) --- .../current/nodes-and-miners/hosted-nodes.md | 25 +++++++++++++++++++ 1 file changed, 25 insertions(+) create mode 100644 i18n/ko/docusaurus-plugin-content-docs/current/nodes-and-miners/hosted-nodes.md diff --git a/i18n/ko/docusaurus-plugin-content-docs/current/nodes-and-miners/hosted-nodes.md b/i18n/ko/docusaurus-plugin-content-docs/current/nodes-and-miners/hosted-nodes.md new file mode 100644 index 0000000000..12d86c7ee2 --- /dev/null +++ b/i18n/ko/docusaurus-plugin-content-docs/current/nodes-and-miners/hosted-nodes.md @@ -0,0 +1,25 @@ +--- +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. From de462df3f4c822453c3a3124949d4dc1a414b5cd Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:42:49 +0100 Subject: [PATCH 0362/1444] New translations authentication.md (Russian) --- .../current/stacks-academy/authentication.md | 63 +++++++++++++++++++ 1 file changed, 63 insertions(+) create mode 100644 i18n/ru/docusaurus-plugin-content-docs/current/stacks-academy/authentication.md diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/stacks-academy/authentication.md b/i18n/ru/docusaurus-plugin-content-docs/current/stacks-academy/authentication.md new file mode 100644 index 0000000000..8152a401f9 --- /dev/null +++ b/i18n/ru/docusaurus-plugin-content-docs/current/stacks-academy/authentication.md @@ -0,0 +1,63 @@ +--- +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/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. From 1fa028ba9dab8d3b7a1e1351815852ec4d384ddb Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:42:50 +0100 Subject: [PATCH 0363/1444] New translations bns.md (Russian) --- .../current/stacks-academy/bns.md | 242 ++++++++++++++++++ 1 file changed, 242 insertions(+) create mode 100644 i18n/ru/docusaurus-plugin-content-docs/current/stacks-academy/bns.md diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/stacks-academy/bns.md b/i18n/ru/docusaurus-plugin-content-docs/current/stacks-academy/bns.md new file mode 100644 index 0000000000..4c89d9e56c --- /dev/null +++ b/i18n/ru/docusaurus-plugin-content-docs/current/stacks-academy/bns.md @@ -0,0 +1,242 @@ +--- +title: Blockchain Naming System +description: Binds Stacks usernames to off-chain state +sidebar_position: 8 +--- + +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 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). From 9cbee0b95bf77770ea8c14c2efcdbfad6481c204 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:42:51 +0100 Subject: [PATCH 0364/1444] New translations docs.md (Russian) --- .../current/contribute/docs.md | 24 ++++++++++++------- 1 file changed, 15 insertions(+), 9 deletions(-) diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/contribute/docs.md b/i18n/ru/docusaurus-plugin-content-docs/current/contribute/docs.md index 77705451b8..b2fef628f9 100644 --- a/i18n/ru/docusaurus-plugin-content-docs/current/contribute/docs.md +++ b/i18n/ru/docusaurus-plugin-content-docs/current/contribute/docs.md @@ -7,7 +7,7 @@ description: Learn how this site is built, and how you can contribute to it. 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). +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/). @@ -15,7 +15,7 @@ Don't want to learn it? No need to. Write [in plain text an issue on Github](htt :::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 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). @@ -24,28 +24,32 @@ To add new content, they are two different ways to do it, the [easy way](#easy-w [**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. +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 yourhanges in real time. + - `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. -## Aditional information +## 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 ``` @@ -54,8 +58,8 @@ Before running this command for the first time you will need to run `npm install 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 ``` @@ -91,7 +95,7 @@ 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. +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 @@ -124,6 +128,7 @@ And execute prettier with the following command: npx prettier --write mynewfiletocheck.md ``` --> + ### 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. @@ -138,6 +143,7 @@ To write a code block, you need to wrap your code in ` ```language `, and end yo (define-public (get-counter) (ok (var-get counter))) ``` + ### Admonitions You can use the following admonitions to highlight content. @@ -204,4 +210,4 @@ Some **content** with _markdown_ `syntax`. Some **content** with _markdown_ `syntax`. -::: \ No newline at end of file +::: From e18444e6fb9b550f8003d6a26db9b77fe2af59c4 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:42:52 +0100 Subject: [PATCH 0365/1444] New translations translations.md (Russian) --- .../current/contribute/translations.md | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/contribute/translations.md b/i18n/ru/docusaurus-plugin-content-docs/current/contribute/translations.md index bd9a452333..fe8f8c6027 100644 --- a/i18n/ru/docusaurus-plugin-content-docs/current/contribute/translations.md +++ b/i18n/ru/docusaurus-plugin-content-docs/current/contribute/translations.md @@ -1,25 +1,24 @@ --- title: Contribute with translations -description: Want to help tranlating these docs to your local language? +description: Want to help translating 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. +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 Crodin intead. +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 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 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) From 4ad8f62e13da34586eb70b346a2cbc8e3eae45a5 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:42:55 +0100 Subject: [PATCH 0366/1444] New translations gaia-on-ec2.md (Russian) --- .../current/gaia/gaia-on-ec2.md | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) 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 index 2067e7d57c..3f58ca5e68 100644 --- 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 @@ -26,9 +26,10 @@ Use a link in the table to launch the [CloudFormation](https://console.aws.amazo ### Step 2 - Setup stack using template -You need to configure the template with the appropiate values for your hub and domain it runs on. +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 ``` @@ -52,7 +53,7 @@ Specify the stack details and then click `Next`: ![Specify template](/img/cloudf | 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`. | +| 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 | @@ -93,7 +94,9 @@ ssh -i admin@ 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 +![](/img/cloudformation-gaia-template1-designer.png) From 2e58da166413e062e8a9af1fbcc4086533e7f9f0 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:42:55 +0100 Subject: [PATCH 0367/1444] New translations gaia.md (Russian) --- .../current/gaia/gaia.md | 12 +++++++++--- 1 file changed, 9 insertions(+), 3 deletions(-) diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/gaia/gaia.md b/i18n/ru/docusaurus-plugin-content-docs/current/gaia/gaia.md index 1070857350..f86a0d61dc 100644 --- a/i18n/ru/docusaurus-plugin-content-docs/current/gaia/gaia.md +++ b/i18n/ru/docusaurus-plugin-content-docs/current/gaia/gaia.md @@ -1,14 +1,20 @@ --- title: Gaia description: Decentralized storage architecture for off-chain data -sidebar_position: 5 +sidebar_position: 6 tags: - gaia --- ## Introduction -Apps built with the Stacks blockchain store off-chain data using a storage system called Gaia. +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. @@ -38,7 +44,7 @@ The Stacks blockchain stores only identity data. Data created by the actions of 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) +![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. From 8edd0b0fd23686584133da9a896fc1abde56de94 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:42:56 +0100 Subject: [PATCH 0368/1444] New translations setup-linux.md (Russian) --- .../current/gaia/setup-linux.md | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) 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 index db427f890a..2c0ca2b92e 100644 --- a/i18n/ru/docusaurus-plugin-content-docs/current/gaia/setup-linux.md +++ b/i18n/ru/docusaurus-plugin-content-docs/current/gaia/setup-linux.md @@ -1,6 +1,6 @@ --- 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. +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 @@ -19,8 +19,7 @@ This configuration will setup the following 4 docker containers: 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: +**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 @@ -48,8 +47,7 @@ chmod +x ${DESTINATION_DC}/docker-compose 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. +**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 From 75ef2cb24a36c566a88cfbf772d3bfadbf3ae1f6 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:42:58 +0100 Subject: [PATCH 0369/1444] New translations digitalocean.md (Russian) --- .../current/nodes-and-miners/digitalocean.md | 41 +++++++++++-------- 1 file changed, 25 insertions(+), 16 deletions(-) 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 index dd7194f504..15df918d04 100644 --- 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 @@ -1,28 +1,30 @@ --- -title: Stacks on DigitalOcean +title: Run a Node with Digital Ocean description: A guide to setup Stacks on DigitalOcean -sidebar_position: 4 +sidebar_position: 2 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). +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`. +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 plan that meets the minimum requirements) and your prefered datacenter region. ![](/img/sh_digitalocean-choose-plan.png) +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 if your prefer. +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) @@ -46,41 +48,48 @@ Congratulations! You are now running the Stacks Blockchain. You can click on `Co ## 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). +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`. -Once the stacks blockchain starts to sync with peers, application ports will open and nginx port 80 will now start proxying requests. +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 v3.0.3 (master:cd0c8aef)", + "server_version": "stacks-blockchain-api v6.2.3 (master:77ab3ae2)", "status": "ready", "chain_tip": { - "block_height": 16220, - "block_hash": "0x3123fba9c0de6b569573494cf83c1d5d198a66bfd5f48ef97949b6bf11ba13be", - "index_block_hash": "0xeec960fbbd6186b4ccac85ce12adba72be497d881f81e077305c90955b51a6ae" + "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/README.md#quickstart). +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). -## API Creation +## 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 -curl -X POST -H 'Content-Type: application/json' \ +$ export TOKEN= +$ 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"}' \ + '{"name":"stacks-blockchain","region":"sfo2","size":"s-2vcpu-4gb","image":"stacksfoundation-stacksblockchain"}' \ "https://api.digitalocean.com/v2/droplets" ``` From ea3d27797e178e0157b01454a06fb649b9713b4c Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:42:59 +0100 Subject: [PATCH 0370/1444] New translations index.md (Russian) --- .../current/nodes-and-miners/index.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) 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 index b6cbb9754a..e5f4f2c250 100644 --- 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 @@ -1,11 +1,11 @@ --- title: Nodes and Miners description: Nodes and Miners -sidebar_position: 7 +sidebar_position: 5 --- -Here are all the steps to run nodes and miners, both on mainnet and testnet. +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. -## What's a Stacks node? +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. -## What's a Stacks miner? +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. From 8b61a3998783b80b80c5cf6ad6c5a8016fd916c2 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:43:00 +0100 Subject: [PATCH 0371/1444] New translations miner-mainnet.md (Russian) --- .../current/nodes-and-miners/miner-mainnet.md | 301 +++++++----------- 1 file changed, 110 insertions(+), 191 deletions(-) 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 index 061f4a2511..5afd34c23f 100644 --- 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 @@ -1,166 +1,100 @@ --- title: Mine mainnet Stacks tokens -description: Set up and run a miner on the Stacks 2.0 mainnet -sidebar_position: 5 +description: Set up and run a miner on Stacks Mainnet +sidebar_position: 6 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. +For more on the technical details of mining, please review the [mining guide](../stacks-academy/mining) -If you're interested in mining on the testnet, you can find instructions on how to do that [here](miner-testnet): +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 want to learn more about the technical details of mining, please review the [mining guide](../understand-stacks/mining): +If you're interested in mining on the Stacks testnet, you can find instructions on how to do that [here](miner-testnet): -## Running bitcoind locally +## Running a Bitcoin Mainnet Full Node -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) +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. -First, download the bitcoind software for your platform from https://bitcoin.org/en/download. +- [Ensure your computer meets the minimum hardware requirements before continuing.](https://bitcoin.org/en/bitcoin-core/features/requirements#system-requirements) -Next, start bitcoind with the following configuration: +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): -```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 -``` +:::tip It is recommened to use a persistent location for the chainstate, in the steps below we're using `/bitcoin` ::: -Finally, start bitcoind as follows: +### Update the Bitcoin Configuration File -```bash -bitcoind -conf=path/to/bitcoin.conf -``` - -It may take a few days for the node to synchronize with the Bitcoin mainnet. +Next, update the bitcoin configuration: -## 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: +- **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 -[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 = "" -... +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 ``` -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. +### Start Bitcoin -To run your miner, run this in the command line: +Finally, start bitcoin as follows (adjust the `conf` path to where it was created in the previous step, i.e. `$HOME/bitcoin.conf`): ```bash -stacks-node start --config=./testnet/stacks-node/conf/mainnet-miner-conf.toml +bitcoind -conf=$HOME/bitcoin.conf ``` -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 -``` +:::note +It will take a few days for the node to synchronize with Bitcoin mainnet. +::: -The above code will compile an optimized binary. To use it, run: +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 -cd ../.. -./target/release/stacks-node start --config=./mainnet-miner-conf.toml +$ bitcoin-cli \ + -rpcconnect=localhost \ + -rpcport=8332 \ + -rpcuser=btcuser \ + -rpcpassword=btcpassword \ +getblockchaininfo | jq .blocks +773281 ``` -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 Stacks Blockchain miner -## Running a miner in Windows +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) -### Prerequisites +_There may be some extra requirements to building, [defined here](https://github.com/stacksfoundation/miner-docs/blob/main/prerequisites.md#install-required-packages)_ -Make sure are [running a node](run-a-node) and [running bitcoind locally](#running-bitcoind-locally) before starting this tutorial. +:::tip It is recommened to use a persistent location for the chainstate, in the steps below we're using `/stacks-blockchain` ::: -### Generate keychain and get mainnet tokens in Windows +### Generate a keychain -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 cryptocurrency 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: +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 -npm install --global @stacks/cli -stx make_keychain > cli_keychain.json -type cli_keychain.json +npx @stacks/cli make_keychain 2>/dev/null | jq -r ``` -After this runs, you'll probably see some installation logs, and at the end you should see some JSON that looks like this: +After this runs, you should see some JSON printed to the screen that looks like this: ```json { @@ -174,109 +108,99 @@ After this runs, you'll probably see some installation logs, and at the end you } ``` -:::tip Check out the [Stacks CLI reference](https://docs.hiro.so/references/stacks-cli) for more details ::: +:::warning **Do not lose this information** - we'll need to use the `privateKey` and `btcAddress` fields in later steps. ::: -The above BTC address will then need to be imported into the BTC network. +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=your-user -rpcpassword=your-password importaddress +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 configuration file + + +### Update the Stacks Blockchain 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). +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`. -Update the following properties: +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] -... -# Enter your private key here -seed = "replace-with-your-private-key" -local_peer_seed = "replace-with-your-private-key" -... +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] -... -# To mine on mainnet, you need to run bitcoind locally -# Details can be found in above section, 'Running bitcoind locally' +chain = "bitcoin" +mode = "mainnet" peer_host = "127.0.0.1" -username = "" -password = "" -... +username = "" +password = "" +rpc_port = 8332 +peer_port = 8333 +satoshis_per_byte = 100 +burn_fee_cap = 20000 ``` -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 +### Start the Stacks Blockchain -To start your miner, run this in the command line: +To run your miner, run this in the command line: ```bash -stacks-node start --config=testnet/stacks-node/conf/mainnet-miner-conf.toml +stacks-node start --config=$HOME/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 +### 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 -set RUST_BACKTRACE=full; -set STACKS_LOG_DEBUG=1; -stacks-node start --config=mainnet-miner-conf.toml +STACKS_LOG_DEBUG=1 stacks-node start --config=$HOME/mainnet-miner-conf.toml ``` -## Optional: Running with Docker +--- + +## Optional: Running a Stacks Blockchain miner with Docker -Alternatively, you can run the mainnet node with Docker. +Alternatively, you can run a Stacks mainnet miner with Docker. -:::caution Ensure you have [Docker](https://docs.docker.com/get-docker/) installed on your machine. ::: +:::caution Ensure you have [Docker](https://docs.docker.com/get-docker/) installed. ::: -### Generate keychain and get tokens +### 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 +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 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: +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). -```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 = "" -... -``` +### Update Stacks Blockchain Docker Configuration File -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. +Use the steps oulined above to create the [configuration file](miner-mainnet#update-the-stacks-blockchain-configuration-file) -### Start the miner +### 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 ::: @@ -287,7 +211,8 @@ docker run -d \ --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" \ + -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 \ @@ -302,9 +227,9 @@ 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). +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 on your machine: +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) @@ -313,13 +238,7 @@ Ensure you have the following prerequisites installed on your machine: ### 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). +Use the steps [outlined above](miner-mainnet#generate-a-keychain-and-get-some-tokens) ### Install the chart and run the miner From 4a5132551094871b833e946bfb2faf7bdf8e386b Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:43:01 +0100 Subject: [PATCH 0372/1444] New translations miner-testnet.md (Russian) --- .../current/nodes-and-miners/miner-testnet.md | 318 +++++++----------- 1 file changed, 130 insertions(+), 188 deletions(-) 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 index 56374190c1..c0a27e63d5 100644 --- 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 @@ -1,35 +1,52 @@ --- title: Mine testnet Stacks tokens -description: Set up and run a miner on the Stacks 2.0 testnet -sidebar_position: 4 +description: Set up and run a miner on Stacks Testnet +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 testnet. +For more on the technical details of mining, please review the [mining guide](../stacks-academy/mining) -If you want to learn more about the technical details of mining, please review the [mining guide](../understand-stacks/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)). -## Running bitcoind locally +If you're interested in mining on the Stacks mainnet, you can find instructions on how to do that [here](miner-mainnet): -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) +## Running a Bitcoin Testnet Full Node -First, download the bitcoind software for your platform from https://bitcoin.org/en/download. +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. -Next, start bitcoind with the following configuration: +- [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 -rpcuser=your-bitcoind-username -rpcpassword=your-bitcoind-password testnet=1 -txindex=0 -listen=1 -rpcserialversion=0 -maxorphantx=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 @@ -37,126 +54,51 @@ 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" -... +### Start Bitcoin -[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: +Finally, start bitcoind as follows: ```bash -stacks-node start --config=./testnet/stacks-node/conf/testnet-miner-conf.toml +bitcoind -conf=$HOME/bitcoin.conf ``` -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 -``` +:::note +It will take a few hours for the node to synchronize with Bitcoin testnet. +::: -The above code will compile an optimized binary. To use it, run: +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 -cd ../.. -./target/release/stacks-node start --config=./testnet/conf/testnet-follower-conf.toml +$ bitcoin-cli \ + -rpcconnect=localhost \ + -rpcport=18332 \ + -rpcuser=btcuser \ + -rpcpassword=btcpass \ +getblockchaininfo | jq .blocks +2417570 ``` -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 +## Running a Stacks Blockchain miner -### Prerequisites +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) -Make sure are [running a testnet node](run-a-node) before starting this tutorial. +_There may be some extra requirements to building, [defined here](https://github.com/stacksfoundation/miner-docs/blob/main/prerequisites.md#install-required-packages)_ -### Generate keychain and get testnet tokens in Windows +:::tip It is recommened to use a persistent location for the chainstate, in the steps below we're using `/stacks-blockchain` ::: -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. +### Generate a keychain -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. +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. -Generate a keychain: +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 -npm install --global @stacks/cli -stx make_keychain -t > cli_keychain.json -type cli_keychain.json +npx @stacks/cli make_keychain -t 2>/dev/null | jq -r ``` -After this runs, you'll probably see some installation logs, and at the end you should see some JSON that looks like this: +After this runs, you should see some JSON printed to the screen that looks like this: ```json { @@ -170,107 +112,110 @@ After this runs, you'll probably see some installation logs, and at the end you } ``` -:::tip Check out the [Stacks CLI reference](https://docs.hiro.so/references/stacks-cli) for more details ::: +:::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. -Request BTC from faucet: +### Update the Stacks Blockchain Configuration File -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/). +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`. -### Update configuration file +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. -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). +Next, update the bitcoin configuration: -Update the following properties: +- **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] -... -seed = "replace-with-your-private-key" -local_peer_seed = "replace-with-your-private-key" -... +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] -... -# To mine on Testnet, you need to run bitcoind locally -# Details can be found in above section, 'Running bitcoind locally' +chain = "bitcoin" +mode = "xenon" peer_host = "127.0.0.1" -username = "" -password = "" -... +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 ``` -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 +### Start the Stacks Blockchain -To start your miner, run this in the command line: +To run your miner, run this in the command line: ```bash -stacks-node start --config=testnet/stacks-node/conf/testnet-miner-conf.toml +stacks-node start --config=$HOME/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 +### 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 -set RUST_BACKTRACE=full; -set STACKS_LOG_DEBUG=1; -stacks-node start --config=testnet-miner-conf.toml +STACKS_LOG_DEBUG=1 stacks-node start --config=$HOME/testnet-miner-conf.toml ``` -## Optional: Running with Docker +--- + +## Optional: Running a Stacks Blockchain miner with Docker -Alternatively, you can run the testnet node with Docker. +Alternatively, you can run a Stacks testnet miner with Docker. -:::warning Ensure you have [Docker](https://docs.docker.com/get-docker/) installed on your machine. ::: +:::caution Ensure you have [Docker](https://docs.docker.com/get-docker/) installed ::: -### Generate keychain and get testnet tokens +### Generate a Keychain and Get Some Tokens Generate a keychain: ```bash -docker run -i node:14-alpine npx @stacks/cli make_keychain -t 2>/dev/null +docker run -i node:14-alpine npx @stacks/cli make_keychain 2>/dev/null | jq -r ``` -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 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. -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 Stacks Blockchain Docker Configuration File -Update the following properties: +Use the steps oulined above to create the [configuration file](miner-testnet#update-the-stacks-blockchain-configuration-file) -```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 +### 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 ::: @@ -281,7 +226,8 @@ docker run -d \ --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" \ + -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 \ @@ -294,26 +240,22 @@ You can review the node logs with this command: 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). +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 on your machine: +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 testnet tokens - -Generate a keychain: - -```bash -docker run -i node:14-alpine npx @stacks/cli make_keychain -t 2>/dev/null -``` +### Generate keychain and get some tokens -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/). +Use the steps [outlined above](miner-testnet#generate-a-keychain-and-get-some-tokens) ### Install the chart and run the miner @@ -324,7 +266,7 @@ 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.node.seed="replace-with-your-privateKey-from-generate-keychain-step" \ ``` You can review the node logs with this command: From 3bdce68c5745b18ee954856d1b2ad8c324043b74 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:43:02 +0100 Subject: [PATCH 0373/1444] New translations stacks-node-configuration.md (Russian) --- .../stacks-node-configuration.md | 173 +++++++++++------- 1 file changed, 111 insertions(+), 62 deletions(-) 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 index 40b2ef676b..cd216e7103 100644 --- 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 @@ -1,7 +1,7 @@ --- title: Stacks Node Configuration description: Configuration parameters and options for the stacks-node binary -sidebar_position: 6 +sidebar_position: 4 --- ## Usage @@ -10,97 +10,141 @@ sidebar_position: 6 stacks-node sub-command [--subcommand-option ] ``` -## Subcommands +### 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 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 -### mocknet +## Configuration File Options -Start a node based on a fast local setup emulating a burnchain. Ideal for smart contract development. +The Stacks Blockchain configuration file has multiple sections under which an option may be placed. -Example: +- [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) -```bash -stacks-node mocknet -``` +For reference, several configuration file examples are [available here](https://github.com/stacks-network/stacks-blockchain/tree/master/testnet/stacks-node/conf) -### krypton +- [Example mainnet follower configuration](./stacks-node-configuration#example-mainnet-follower-configuration) -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). +### node -Example: +Contains various configuration options for the stacks-node binary. -```bash -stacks-node krypton -``` +| 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. | -### testnet +### events_observer -Start a node that will join and stream blocks from the public testnet. +:::info This section is _optional_ and not required -Example: +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. -```bash -stacks-node testnet -``` +| 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. | | -### mainnet +### connection_options -Start a node that joins and streams blocks from the public mainnet. +:::info This section is _optional_ and not required. -Example: +However, if this section is added, **all** fields are required ::: -```bash -stacks-node mainnet -``` +Specifies configuration options for others connecting to the stacks node. -### start +| 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 | -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. +### burnchain -#### Arguments +This section contains configuration options pertaining to the blockchain the stacks-node binds to on the backend for proof-of-transfer (BTC). -**--config**: relative or absolute path to the TOML config file. Required. +| 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` | -Example: +#### Mining -```bash -stacks-node start --config=/path/to/config.toml -``` +| 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`. | -See [Configuration File Options](#configuration-file-options) for more information. +### ustx_balance -#### version +- `mocknet`/`testnet` only -Displays information about the current version and the release cycle. +This section contains configuration options allocating microSTX per address in the genesis block -Example: +This section can repeat multiple times, but each section can only define a single address. -```bash -stacks-node version -``` +:::info This section is only required for the `testnet` and `mocknet` networks. -#### help +However, if this section is added, **all** fields are required ::: -Displays a help message. +| 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: +## Example Mainnet Follower Configuration -```bash -stacks-node help -``` - -## Configuration File Options - -The TOML configuration file has multiple sections under which an option may be placed. +```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" -To see a list of example configurations, [please see this page](https://github.com/stacks-network/stacks-blockchain/tree/master/testnet/stacks-node/conf). +[burnchain] +chain = "bitcoin" +mode = "mainnet" +peer_host = "localhost" +username = "user" +password = "pass" +rpc_port = 8332 +peer_port = 8333 -### Section: node +[[events_observer]] +endpoint = "localhost:3700" +retry_count = 255 +events_keys = ["*"] +``` -Contains various configuration options pertaining to the stacks-node. -Example: + From 242ac2e297228f453da409d727a316fee722a1a4 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:43:03 +0100 Subject: [PATCH 0374/1444] New translations accounts.md (Russian) --- .../current/stacks-academy/accounts.md | 215 ++++++++++++++++++ 1 file changed, 215 insertions(+) create mode 100644 i18n/ru/docusaurus-plugin-content-docs/current/stacks-academy/accounts.md diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/stacks-academy/accounts.md b/i18n/ru/docusaurus-plugin-content-docs/current/stacks-academy/accounts.md new file mode 100644 index 0000000000..55d0165def --- /dev/null +++ b/i18n/ru/docusaurus-plugin-content-docs/current/stacks-academy/accounts.md @@ -0,0 +1,215 @@ +--- +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" + } + } + ] +} +``` From 4c267a477f0ee6c9c4fbc08bcf7246f406d666c6 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:43:04 +0100 Subject: [PATCH 0375/1444] New translations microblocks.md (Russian) --- .../current/stacks-academy/microblocks.md | 107 ++++++++++++++++++ 1 file changed, 107 insertions(+) create mode 100644 i18n/ru/docusaurus-plugin-content-docs/current/stacks-academy/microblocks.md diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/stacks-academy/microblocks.md b/i18n/ru/docusaurus-plugin-content-docs/current/stacks-academy/microblocks.md new file mode 100644 index 0000000000..9310aa65be --- /dev/null +++ b/i18n/ru/docusaurus-plugin-content-docs/current/stacks-academy/microblocks.md @@ -0,0 +1,107 @@ +--- +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. + +[provides an endpoint]: https://docs.hiro.so/get-started/stacks-blockchain-api#nonce-handling +[microblocks_api]: https://docs.hiro.so/api#tag/Microblocks From 6123f0c3bfad78062db19e22e984c94ee958a7b9 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:43:05 +0100 Subject: [PATCH 0376/1444] New translations mining.md (Russian) --- .../current/stacks-academy/mining.md | 84 +++++++++++++++++++ 1 file changed, 84 insertions(+) create mode 100644 i18n/ru/docusaurus-plugin-content-docs/current/stacks-academy/mining.md diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/stacks-academy/mining.md b/i18n/ru/docusaurus-plugin-content-docs/current/stacks-academy/mining.md new file mode 100644 index 0000000000..e6e93e130a --- /dev/null +++ b/i18n/ru/docusaurus-plugin-content-docs/current/stacks-academy/mining.md @@ -0,0 +1,84 @@ +--- +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 From eb26100e75e3e1c7e50598d975449ac3b3dc4a33 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:43:05 +0100 Subject: [PATCH 0377/1444] New translations network.md (Russian) --- .../current/stacks-academy/network.md | 151 ++++++++++++++++++ 1 file changed, 151 insertions(+) create mode 100644 i18n/ru/docusaurus-plugin-content-docs/current/stacks-academy/network.md diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/stacks-academy/network.md b/i18n/ru/docusaurus-plugin-content-docs/current/stacks-academy/network.md new file mode 100644 index 0000000000..dd50cb7ee1 --- /dev/null +++ b/i18n/ru/docusaurus-plugin-content-docs/current/stacks-academy/network.md @@ -0,0 +1,151 @@ +--- +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 +} +``` From ac1533b3c1fa10ecd01efcf4ed2904e302c854ae Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:43:06 +0100 Subject: [PATCH 0378/1444] New translations stacking.md (Russian) --- .../current/stacks-academy/stacking.md | 151 ++++++++++++++++++ 1 file changed, 151 insertions(+) create mode 100644 i18n/ru/docusaurus-plugin-content-docs/current/stacks-academy/stacking.md diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/stacks-academy/stacking.md b/i18n/ru/docusaurus-plugin-content-docs/current/stacks-academy/stacking.md new file mode 100644 index 0000000000..545f538ecb --- /dev/null +++ b/i18n/ru/docusaurus-plugin-content-docs/current/stacks-academy/stacking.md @@ -0,0 +1,151 @@ +--- +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. 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. + +![](/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 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 (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 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) From dd22a774d12181973bdf389fb08f6809717450c5 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:43:07 +0100 Subject: [PATCH 0379/1444] New translations technical-specs.md (Russian) --- .../current/stacks-academy/technical-specs.md | 79 +++++++++++++++++++ 1 file changed, 79 insertions(+) create mode 100644 i18n/ru/docusaurus-plugin-content-docs/current/stacks-academy/technical-specs.md diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/stacks-academy/technical-specs.md b/i18n/ru/docusaurus-plugin-content-docs/current/stacks-academy/technical-specs.md new file mode 100644 index 0000000000..695f849e1a --- /dev/null +++ b/i18n/ru/docusaurus-plugin-content-docs/current/stacks-academy/technical-specs.md @@ -0,0 +1,79 @@ +--- +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). +- 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 whitepaper v2](https://www.youtube.com/watch?v=Wd-Bfe8Sn-Y). From 2fd1ac7618e5f7edfb25e56bf5f6a76e332824cd Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:43:08 +0100 Subject: [PATCH 0380/1444] New translations testnet.md (Russian) --- .../current/stacks-academy/testnet.md | 35 +++++++++++++++++++ 1 file changed, 35 insertions(+) create mode 100644 i18n/ru/docusaurus-plugin-content-docs/current/stacks-academy/testnet.md diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/stacks-academy/testnet.md b/i18n/ru/docusaurus-plugin-content-docs/current/stacks-academy/testnet.md new file mode 100644 index 0000000000..f8b9f03df2 --- /dev/null +++ b/i18n/ru/docusaurus-plugin-content-docs/current/stacks-academy/testnet.md @@ -0,0 +1,35 @@ +--- +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. + +### 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) From 0f3a273d2a9828184d5afd9c77064057357fa1cb Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:43:09 +0100 Subject: [PATCH 0381/1444] New translations transactions.md (Russian) --- .../current/stacks-academy/transactions.md | 40 +++++++++++++++++++ 1 file changed, 40 insertions(+) create mode 100644 i18n/ru/docusaurus-plugin-content-docs/current/stacks-academy/transactions.md diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/stacks-academy/transactions.md b/i18n/ru/docusaurus-plugin-content-docs/current/stacks-academy/transactions.md new file mode 100644 index 0000000000..ba6b18f0f7 --- /dev/null +++ b/i18n/ru/docusaurus-plugin-content-docs/current/stacks-academy/transactions.md @@ -0,0 +1,40 @@ +--- +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). ::: From 71d53bf12e5cade11dff0f56100881364986614b Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:43:10 +0100 Subject: [PATCH 0382/1444] New translations language-functions.md (Russian) --- .../current/clarity/language-functions.md | 2031 +++++++++++++++++ 1 file changed, 2031 insertions(+) create mode 100644 i18n/ru/docusaurus-plugin-content-docs/current/clarity/language-functions.md diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/clarity/language-functions.md b/i18n/ru/docusaurus-plugin-content-docs/current/clarity/language-functions.md new file mode 100644 index 0000000000..0325c1ac40 --- /dev/null +++ b/i18n/ru/docusaurus-plugin-content-docs/current/clarity/language-functions.md @@ -0,0 +1,2031 @@ +--- +title: Functions +description: See a detailed list of all functions for the Clarity language. +sidebar_position: 3 +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: + +#### 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-existent\"))))) ;; 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-existent\") ;; 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-existent\" })) ;; 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-existent\" }))) ;; 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-existent\" }))) ;; 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 \"Stacks\" '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 successfully 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_ transferred from another principal, but rather minted. + +If a non-positive amount is provided to mint, this function returns `(err 1)`. Otherwise, on successfully 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_ transferred 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 successfully 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 successfully 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)) +``` From f3d97c9cb214b300d6c0ea5493439e7b5cff543e Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:43:11 +0100 Subject: [PATCH 0383/1444] New translations language-keywords.md (Russian) --- .../current/clarity/language-keywords.md | 146 ++++++++++++++++++ 1 file changed, 146 insertions(+) create mode 100644 i18n/ru/docusaurus-plugin-content-docs/current/clarity/language-keywords.md diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/clarity/language-keywords.md b/i18n/ru/docusaurus-plugin-content-docs/current/clarity/language-keywords.md new file mode 100644 index 0000000000..1aca5359c3 --- /dev/null +++ b/i18n/ru/docusaurus-plugin-content-docs/current/clarity/language-keywords.md @@ -0,0 +1,146 @@ +--- +title: Keywords +description: See a detailed list of all keywords for the Clarity language. +sidebar_position: 4 +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 +``` From 9ad075fd5a2550353d64456f40547cea4f6ccc0b Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:43:12 +0100 Subject: [PATCH 0384/1444] New translations language-types.md (Russian) --- .../current/clarity/language-types.md | 25 +++++++++++++++++++ 1 file changed, 25 insertions(+) create mode 100644 i18n/ru/docusaurus-plugin-content-docs/current/clarity/language-types.md diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/clarity/language-types.md b/i18n/ru/docusaurus-plugin-content-docs/current/clarity/language-types.md new file mode 100644 index 0000000000..0af4577dc9 --- /dev/null +++ b/i18n/ru/docusaurus-plugin-content-docs/current/clarity/language-types.md @@ -0,0 +1,25 @@ +--- +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. | From 10d703276b1eb724ab6d4ccd5914c5bb6c08a8f6 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:43:14 +0100 Subject: [PATCH 0385/1444] New translations miner-costs-and-fees.md (Russian) --- .../current/nodes-and-miners/miner-costs-and-fees.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) 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 index 40397a51e0..dd8ee721cc 100644 --- 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 @@ -8,7 +8,7 @@ sidebar_position: 8 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 @@ -22,3 +22,5 @@ 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). From 2c45aa2a127f089650105413207bd135ab774e8c Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:43:15 +0100 Subject: [PATCH 0386/1444] New translations verify-miner.md (Russian) --- .../current/nodes-and-miners/verify-miner.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) 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 index 094e3f03a1..18e8dd3a48 100644 --- 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 @@ -7,7 +7,7 @@ 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 +$ 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 -``` \ No newline at end of file +``` From 98277fb2ffc0e3e80f37c05b69f9a944ebb8dd7b Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:43:15 +0100 Subject: [PATCH 0387/1444] New translations stacks-blockchain-api.md (Russian) --- .../stacks-academy/stacks-blockchain-api.md | 41 +++++++++++++++++++ 1 file changed, 41 insertions(+) create mode 100644 i18n/ru/docusaurus-plugin-content-docs/current/stacks-academy/stacks-blockchain-api.md diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/stacks-academy/stacks-blockchain-api.md b/i18n/ru/docusaurus-plugin-content-docs/current/stacks-academy/stacks-blockchain-api.md new file mode 100644 index 0000000000..ad9bb1822e --- /dev/null +++ b/i18n/ru/docusaurus-plugin-content-docs/current/stacks-academy/stacks-blockchain-api.md @@ -0,0 +1,41 @@ +--- +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`. ::: From 388354298806465a52a18b659304096b1ab7ed49 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:43:16 +0100 Subject: [PATCH 0388/1444] New translations run-a-node.md (Russian) --- .../current/nodes-and-miners/run-a-node.md | 329 +++--------------- 1 file changed, 42 insertions(+), 287 deletions(-) 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 index 94d938c5ca..2993568ce4 100644 --- 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 @@ -1,5 +1,5 @@ --- -title: Run a node +title: Run a Node with Docker description: Set up and run a Stacks node sidebar_position: 1 tags: @@ -8,344 +8,99 @@ tags: ## Stacks Blockchain with Docker -Run your own Stacks Blockchain node easily with just few commands. +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) -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](./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) -## **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 -``` +## **Requirements:** -- With optional proxy: +The **minimum viable requirements** are listed below. -```bash -./manage.sh -n -a start -f proxy -``` +While you _can_ run a node using these specs, it's _recommended_ to assign more than the minimum for better performance. -- With optional bitcoin node: +- ⚠️ [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_ ) -```bash -./manage.sh -n -a start -f bitcoin -``` +:::caution MacOS with an ARM processor is NOT recommended -5. **Stop the Services** +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. ::: -```bash -./manage.sh -n -a stop -``` - -6. **Retrieve Service Logs** - -```bash -./manage.sh -n -a logs -``` - -- Export docker log files to `./exported-logs`: +## **Quickstart** -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. +The `` placeholder used below can be replaced with one of: -```bash -./manage.sh -n -a logs export -``` +- mainnet +- testnet +- mocknet -7. **Restart all services** +1. **Clone the stacks-blockchain-docker repository locally** ```bash -./manage.sh -n -a restart +git clone https://github.com/stacks-network/stacks-blockchain-docker && cd stacks-blockchain-docker ``` -- With optional proxy: +2. **Start the Services** ```bash -./manage.sh -n -a restart -f proxy +./manage.sh -n -a start ``` -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. +:::note With an optional HTTP proxy on port 80: ```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. - +./manage.sh -n -a start -f proxy ``` -9. **Download BNS data to** `./persistent-data/bns-data` - -```bash -./manage.sh bns -``` +::: -10. **Export stacks-blockchain-api events** (_Not applicable for mocknet_) +## **Accessing the services** -```bash -./manage.sh -n -a export -# check logs for completion -./manage.sh -n -a restart -``` +:::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. -11. **Replay stacks-blockchain-api events** (_Not applicable for mocknet_) +Follow the logs to track the sync progress: ```bash -./manage.sh -n -a import -# check logs for completion -./manage.sh -n -a restart +./manage.sh -n -a logs ``` -## **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` +- Ports `20443-20444` are exposed on `localhost` ```bash -curl -sL localhost:20443/v2/info | jq +curl -sL localhost:20443/v2/info | jq -r ``` **stacks-blockchain-api**: -- Port `3999` are exposed to `localhost` +- Port `3999` is exposed on `localhost` ```bash -curl -sL localhost:3999/v2/info | jq +curl -sL localhost:3999 | jq -r ``` **proxy**: -- Port `80` is exposed to `localhost` +- Port `80` is exposed on `localhost` ```bash -curl -sL localhost/v2/info | jq -curl -sL localhost/ | jq +curl -sL localhost/v2/info | jq -r +curl -sL localhost | jq -r ``` --- ## 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 -``` +:::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): ::: --- - -## **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 From 4a7e4486979acc098df3dea1cc27d7ceb9b11ce9 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:43:17 +0100 Subject: [PATCH 0389/1444] New translations index.md (Russian) --- .../current/clarity/index.md | 58 +++++++++++++++++++ 1 file changed, 58 insertions(+) create mode 100644 i18n/ru/docusaurus-plugin-content-docs/current/clarity/index.md diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/clarity/index.md b/i18n/ru/docusaurus-plugin-content-docs/current/clarity/index.md new file mode 100644 index 0000000000..903de93a45 --- /dev/null +++ b/i18n/ru/docusaurus-plugin-content-docs/current/clarity/index.md @@ -0,0 +1,58 @@ +--- +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?2 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. If you are unsure what this means, let it not worry you for now. The serious advantage of decidability will become more apparent over time. + +### 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. From 99f13a3fe608d14bf047b9101ac28c3b9ec9a094 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:43:18 +0100 Subject: [PATCH 0390/1444] New translations index.md (Russian) --- .../current/stacks-academy/index.md | 11 +++++++++++ 1 file changed, 11 insertions(+) create mode 100644 i18n/ru/docusaurus-plugin-content-docs/current/stacks-academy/index.md diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/stacks-academy/index.md b/i18n/ru/docusaurus-plugin-content-docs/current/stacks-academy/index.md new file mode 100644 index 0000000000..a5bdb3c790 --- /dev/null +++ b/i18n/ru/docusaurus-plugin-content-docs/current/stacks-academy/index.md @@ -0,0 +1,11 @@ +--- +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. From 6972ebfca00ba918f36810c04f62162d9ac2df5f Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:43:19 +0100 Subject: [PATCH 0391/1444] New translations proof-of-transfer.md (Russian) --- .../stacks-academy/proof-of-transfer.md | 83 +++++++++++++++++++ 1 file changed, 83 insertions(+) create mode 100644 i18n/ru/docusaurus-plugin-content-docs/current/stacks-academy/proof-of-transfer.md diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/stacks-academy/proof-of-transfer.md b/i18n/ru/docusaurus-plugin-content-docs/current/stacks-academy/proof-of-transfer.md new file mode 100644 index 0000000000..50f4b739d6 --- /dev/null +++ b/i18n/ru/docusaurus-plugin-content-docs/current/stacks-academy/proof-of-transfer.md @@ -0,0 +1,83 @@ +--- +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. From 1224b0907f7992866896822c41d1885f86f42049 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:43:19 +0100 Subject: [PATCH 0392/1444] New translations what-is-stacks.md (Russian) --- .../current/stacks-academy/what-is-stacks.md | 102 ++++++++++++++++++ 1 file changed, 102 insertions(+) create mode 100644 i18n/ru/docusaurus-plugin-content-docs/current/stacks-academy/what-is-stacks.md diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/stacks-academy/what-is-stacks.md b/i18n/ru/docusaurus-plugin-content-docs/current/stacks-academy/what-is-stacks.md new file mode 100644 index 0000000000..94277da8a9 --- /dev/null +++ b/i18n/ru/docusaurus-plugin-content-docs/current/stacks-academy/what-is-stacks.md @@ -0,0 +1,102 @@ +--- +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. + +There's a lot of jargon, possible assumptions, controversy, and cool technology wrapped up in those statements. So let's get started by getting a 30,000 foot view of what exactly Stacks is. + +## Stacks Explained in (Slightly Less Than) 10 Minutes + +
+ +
+ +## 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, Stacks takes a different approach. + +## 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). + +By taking this 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 with some unique properties, like having its own token, that allow it to maintain a historical ledger of all of its transactions and operate with its own security budget. + +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_. + +Nope. 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. From 93546b2e1c64ac1ca8e36812906c768d4296c783 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:43:20 +0100 Subject: [PATCH 0393/1444] New translations community-tutorials.md (Russian) --- .../current/tutorials/community-tutorials.md | 24 +++++++++++++++++++ 1 file changed, 24 insertions(+) create mode 100644 i18n/ru/docusaurus-plugin-content-docs/current/tutorials/community-tutorials.md diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/tutorials/community-tutorials.md b/i18n/ru/docusaurus-plugin-content-docs/current/tutorials/community-tutorials.md new file mode 100644 index 0000000000..a4f3d970ca --- /dev/null +++ b/i18n/ru/docusaurus-plugin-content-docs/current/tutorials/community-tutorials.md @@ -0,0 +1,24 @@ +--- +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/) From 4ef40828585862bca66f46afc01f4c5ecea2f5e1 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:43:21 +0100 Subject: [PATCH 0394/1444] New translations hello-stacks.md (Russian) --- .../current/tutorials/hello-stacks.md | 759 ++++++++++++++++++ 1 file changed, 759 insertions(+) create mode 100644 i18n/ru/docusaurus-plugin-content-docs/current/tutorials/hello-stacks.md diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/tutorials/hello-stacks.md b/i18n/ru/docusaurus-plugin-content-docs/current/tutorials/hello-stacks.md new file mode 100644 index 0000000000..a0a442d135 --- /dev/null +++ b/i18n/ru/docusaurus-plugin-content-docs/current/tutorials/hello-stacks.md @@ -0,0 +1,759 @@ +--- +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. From 937df1f188760f4931befbe8e537b49ef448376a Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:43:22 +0100 Subject: [PATCH 0395/1444] New translations index.md (Russian) --- .../current/tutorials/index.md | 11 +++++++++++ 1 file changed, 11 insertions(+) create mode 100644 i18n/ru/docusaurus-plugin-content-docs/current/tutorials/index.md diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/tutorials/index.md b/i18n/ru/docusaurus-plugin-content-docs/current/tutorials/index.md new file mode 100644 index 0000000000..1d544c7bc1 --- /dev/null +++ b/i18n/ru/docusaurus-plugin-content-docs/current/tutorials/index.md @@ -0,0 +1,11 @@ +--- +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. From 9203d87724944f6dafb8be631634a17894a533f2 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:43:23 +0100 Subject: [PATCH 0396/1444] New translations satoshis-ridge.md (Russian) --- .../current/tutorials/satoshis-ridge.md | 75 +++++++++++++++++++ 1 file changed, 75 insertions(+) create mode 100644 i18n/ru/docusaurus-plugin-content-docs/current/tutorials/satoshis-ridge.md diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/tutorials/satoshis-ridge.md b/i18n/ru/docusaurus-plugin-content-docs/current/tutorials/satoshis-ridge.md new file mode 100644 index 0000000000..596339ae74 --- /dev/null +++ b/i18n/ru/docusaurus-plugin-content-docs/current/tutorials/satoshis-ridge.md @@ -0,0 +1,75 @@ +--- +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 arguable one of its strengths. + +Instead, we need to create separate layers that add additional functionality without modify 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. From 54827785be4275b6eedd69797fbbd75226c9c2de Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:43:24 +0100 Subject: [PATCH 0397/1444] New translations crash-course.md (Russian) --- .../current/clarity/crash-course.md | 122 ++++++++++++++++++ 1 file changed, 122 insertions(+) create mode 100644 i18n/ru/docusaurus-plugin-content-docs/current/clarity/crash-course.md diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/clarity/crash-course.md b/i18n/ru/docusaurus-plugin-content-docs/current/clarity/crash-course.md new file mode 100644 index 0000000000..5b27a3c275 --- /dev/null +++ b/i18n/ru/docusaurus-plugin-content-docs/current/clarity/crash-course.md @@ -0,0 +1,122 @@ +--- +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.md). + +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. + +```clojure +(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: + +```clojure +(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. From 92e671dea810ef7eb9b1fba5dca9645ad45a9857 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:43:25 +0100 Subject: [PATCH 0398/1444] New translations sample-contracts.md (Russian) --- .../current/clarity/sample-contracts.md | 14 ++++++++++++++ 1 file changed, 14 insertions(+) create mode 100644 i18n/ru/docusaurus-plugin-content-docs/current/clarity/sample-contracts.md diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/clarity/sample-contracts.md b/i18n/ru/docusaurus-plugin-content-docs/current/clarity/sample-contracts.md new file mode 100644 index 0000000000..adb12a58fd --- /dev/null +++ b/i18n/ru/docusaurus-plugin-content-docs/current/clarity/sample-contracts.md @@ -0,0 +1,14 @@ +--- +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) From 02a745ffe093e585d0b4966a54aab91739954662 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:43:26 +0100 Subject: [PATCH 0399/1444] New translations index.md (Russian) --- .../current/cookbook/index.md | 64 +++++++++++++++++++ 1 file changed, 64 insertions(+) create mode 100644 i18n/ru/docusaurus-plugin-content-docs/current/cookbook/index.md diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/cookbook/index.md b/i18n/ru/docusaurus-plugin-content-docs/current/cookbook/index.md new file mode 100644 index 0000000000..a2b0e42eea --- /dev/null +++ b/i18n/ru/docusaurus-plugin-content-docs/current/cookbook/index.md @@ -0,0 +1,64 @@ +--- +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 + +Swapping between Bitcoin and Stacks addresses + +Swapping between xBTC and BTC + +Verifying a transaction on the BTC chain + +## 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 + +Airdropping an NFT to a Bitcoin address + +## Stacking and Mining + +Simple stacking pool + +Continuous stacking + +Simple mining pool + +Proof of PoX payout + +## Oracles + +Creating a simple BTC price oracle + +## Frontend + +[Post conditions with Stacks.js](./post-conditions) + +[Authentication with Stacks.js](./stacks-js-auth) + +[Sending transactions with Stacks.js](./stacks-js-sending-transactions) + +## Complete Apps + +[Sup](https://github.com/kenrogers/sup) + +[Hello Stacks](https://github.com/kenrogers/hello-stacks) From 4fd3caf24c4c4688acec1e3fb6677628a342b010 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:43:27 +0100 Subject: [PATCH 0400/1444] New translations btc-connection.md (Russian) --- .../current/stacks-academy/btc-connection.md | 196 ++++++++++++++++++ 1 file changed, 196 insertions(+) create mode 100644 i18n/ru/docusaurus-plugin-content-docs/current/stacks-academy/btc-connection.md diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/stacks-academy/btc-connection.md b/i18n/ru/docusaurus-plugin-content-docs/current/stacks-academy/btc-connection.md new file mode 100644 index 0000000000..b4db915969 --- /dev/null +++ b/i18n/ru/docusaurus-plugin-content-docs/current/stacks-academy/btc-connection.md @@ -0,0 +1,196 @@ +--- +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. + +## Stacks Among Other Bitcoin Layers + +In the [last section](./what-is-stacks.md) we covered what Stacks actually is and what problem it is solving, but this is not a new problem. The Bitcoin write problem has been a bit of a holy grail problem in the crypto world for a while now. + +Bitcoin is the OG cryptocurrency and has the largest market cap, but it also some of the least functionality, which means if we want to make it a productive asset and use it to build a decentralized economy, we need to take a layered approach and let Bitcoin do what it does best, while creating additional layers on top of it to add functionality. + +So how does Stacks compare to some of the other approaches to layering on top of Bitcoin? + +### 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. + +## 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. + +But because it has its own execution environment and smart contract state to maintain, it needs a token to incentivize maintenance of the network. + +But it goes further than that. It is possible to build a system like this without a token using something like merge-mining or a sidechain, but then we lose out on the additional benefit of having the chain state's safety underpinned by its entire token economy's value. + +In the case of Stacks, the safety and liveness of the chain are underpinned by this value, and the stacking mechanism incentivizes network members to increase this value. + +From Jude Nelson, Stacks core developer: + +"How hard is it to cause a safety failure (i.e. a double-spend via a reorg) on just the canonical Stacks chain fork? Anyone can become a miner by spending BTC, so without loss of generality, reverting the last block on the canonical chain is at least as hard in expectation as spending more BTC than the rest of the miners combined for that block. Because each Bitcoin block selects at most one Stacks block, the act of reorging the canonical Stacks chain back N blocks is the act of winning at least N + 1 blocks built off of a common ancestor that is N blocks deep. This is a lower bound on the number of Bitcoin blocks mined during which a reorg needs to take place — in practice, honest miners will keep working on the canonical chain, and will win some Stacks blocks of their own, which in turn increases the number of Stacks blocks the reorging miners must win. + +How costly is it to carry out a reorg of N blocks? It’s a function of how valuable STX is relative to BTC — the more valuable STX are, the more BTC honest miners are committing to mining (this has borne out in practice), and thus the more BTC a reorging miner must commit. Therefore, the cost of a reorg is a function of the value of STX. + +This is similar to the economic security of a PoW blockchain. Like in PoW, each fork of the Stacks chain has its own independent “security budget” — an attacker must out-spend the security budget to carry out a reorg, and the security budget is a function of the block rewards. In PoX, the only difference is that the miners spend another blockchain’s tokens (BTC in Stacks’ case) instead of energy. Therefore, Stacks can’t be a sidechain, a drivechain, or a merge-mined chain, because none of these other systems’ security budgets are a function of their tokens’ worth. Sidechains, drivechains, and merged-mined chains all rely on external miners for their safety, since their safety is guaranteed in part by external miners validating their blocks. The onus on these systems is to get external miners to care enough to do so, and in the case of sidechains, drivechains, and blind merged-mined chains, there is an additional onus to encourage their nodes to mine blocks at all (since there is no on-chain reward for them to earn by doing so). By contrast, disinterested Bitcoin miners neither assist nor prevent a reorg in PoX — they only record the history of all Stacks forks. + +PoX offers two additional, unique security properties on top of PoW. First, no matter how much BTC a reorging miner can commit, the act of executing a reorg is going to be time-consuming. Unless the attacker can attack the Bitcoin chain itself by quickly producing a better Bitcoin fork, a reorging miner must sustain the attack for at least N + 1 Bitcoin blocks. This gives honest miners and users ample time to notice and react to the reorg attempt. + +Second, the history of block production in all Stacks forks is embedded within Bitcoin. This allows the system to leverage Bitcoin’s security budget in order to ensure that all forks are public. This is because the act of producing a hidden Stacks fork, where the fork’s block hashes are not known to the honest miners, is the act of producing a hidden canonical Bitcoin fork. Therefore, the act of producing a hidden Stacks fork is at least as hard as reorging the Bitcoin chain. A PoX chain leverages this property not to prevent reorgs, but to make reorgs unprofitable. + +By anchoring blocks to an existing blockchain, a PoX chain forces reorgs to happen out in the open, thereby giving advance warning to all honest network participants when they happen. Honest miners, users, and exchanges will see the PoX transactions for reorg attempts on the existing blockchain, and adapt their behaviors accordingly: honest miners will increase their commitments, and users and exchanges will require more confirmations for transactions. This makes the act of carrying out a reorg while also making a profit much more challenging, since malicious reorgs — like selfish mining and double-spending — rely on secrecy to work effectively. Specific to Stacks, miners are additionally required to mine for a “warm-up” period of two blocks, during which they must spend BTC at their target commit levels but will not win any Stacks blocks. So, a high-budget reorg attempt will not only be costly, but will also alert the rest of the network before the damage is done." + +- [What Kind of Blockchain is Stacks?](https://stacks.org/stacks-blockchain) + +## 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) From e02563641c4fa56683d3b8f23ad1dd6d233eecf1 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:43:28 +0100 Subject: [PATCH 0401/1444] New translations post-conditions.md (Russian) --- .../current/stacks-academy/post-conditions.md | 39 +++++++++++++++++++ 1 file changed, 39 insertions(+) create mode 100644 i18n/ru/docusaurus-plugin-content-docs/current/stacks-academy/post-conditions.md diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/stacks-academy/post-conditions.md b/i18n/ru/docusaurus-plugin-content-docs/current/stacks-academy/post-conditions.md new file mode 100644 index 0000000000..bb0727194f --- /dev/null +++ b/i18n/ru/docusaurus-plugin-content-docs/current/stacks-academy/post-conditions.md @@ -0,0 +1,39 @@ +--- +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). From a4255b20a0389e9f42b79705f5330f26286e8443 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:43:28 +0100 Subject: [PATCH 0402/1444] New translations creating-an-ft.md (Russian) --- .../current/cookbook/creating-an-ft.md | 99 +++++++++++++++++++ 1 file changed, 99 insertions(+) create mode 100644 i18n/ru/docusaurus-plugin-content-docs/current/cookbook/creating-an-ft.md diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/cookbook/creating-an-ft.md b/i18n/ru/docusaurus-plugin-content-docs/current/cookbook/creating-an-ft.md new file mode 100644 index 0000000000..4e3bad99d2 --- /dev/null +++ b/i18n/ru/docusaurus-plugin-content-docs/current/cookbook/creating-an-ft.md @@ -0,0 +1,99 @@ +--- +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) + ) +) +``` From 651d977defccb36af59ead7b747bcf9974a2f195 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:43:29 +0100 Subject: [PATCH 0403/1444] New translations creating-an-nft.md (Russian) --- .../current/cookbook/creating-an-nft.md | 87 +++++++++++++++++++ 1 file changed, 87 insertions(+) create mode 100644 i18n/ru/docusaurus-plugin-content-docs/current/cookbook/creating-an-nft.md diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/cookbook/creating-an-nft.md b/i18n/ru/docusaurus-plugin-content-docs/current/cookbook/creating-an-nft.md new file mode 100644 index 0000000000..08faf9393a --- /dev/null +++ b/i18n/ru/docusaurus-plugin-content-docs/current/cookbook/creating-an-nft.md @@ -0,0 +1,87 @@ +--- +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 +Code for this recipe has been pulled from [this NFT tutorial](https://blog.developerdao.com/building-an-nft-with-stacks-and-clarity) from Developer DAO. +::: + +## 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) + ) +) +``` From a5270ab51443b347546ecc7b4ef3dd42dfe4e3c9 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:43:30 +0100 Subject: [PATCH 0404/1444] New translations post-conditions.md (Russian) --- .../current/cookbook/post-conditions.md | 136 ++++++++++++++++++ 1 file changed, 136 insertions(+) create mode 100644 i18n/ru/docusaurus-plugin-content-docs/current/cookbook/post-conditions.md diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/cookbook/post-conditions.md b/i18n/ru/docusaurus-plugin-content-docs/current/cookbook/post-conditions.md new file mode 100644 index 0000000000..571fc20d48 --- /dev/null +++ b/i18n/ru/docusaurus-plugin-content-docs/current/cookbook/post-conditions.md @@ -0,0 +1,136 @@ +--- +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. From 1a7dfeda394283b3ab7dc51ea6fc68fe0eec42ef Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:43:31 +0100 Subject: [PATCH 0405/1444] New translations stacks-js-auth.md (Russian) --- .../current/cookbook/stacks-js-auth.md | 98 +++++++++++++++++++ 1 file changed, 98 insertions(+) create mode 100644 i18n/ru/docusaurus-plugin-content-docs/current/cookbook/stacks-js-auth.md diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/cookbook/stacks-js-auth.md b/i18n/ru/docusaurus-plugin-content-docs/current/cookbook/stacks-js-auth.md new file mode 100644 index 0000000000..89d1f06e00 --- /dev/null +++ b/i18n/ru/docusaurus-plugin-content-docs/current/cookbook/stacks-js-auth.md @@ -0,0 +1,98 @@ +--- +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 && ( + + ); +} +``` From 9b554d4708a5f6d15985c770514a0251a5afdef6 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:43:32 +0100 Subject: [PATCH 0406/1444] New translations stacks-js-sending-transactions.md (Russian) --- .../stacks-js-sending-transactions.md | 55 +++++++++++++++++++ 1 file changed, 55 insertions(+) create mode 100644 i18n/ru/docusaurus-plugin-content-docs/current/cookbook/stacks-js-sending-transactions.md diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/cookbook/stacks-js-sending-transactions.md b/i18n/ru/docusaurus-plugin-content-docs/current/cookbook/stacks-js-sending-transactions.md new file mode 100644 index 0000000000..849c7d1f42 --- /dev/null +++ b/i18n/ru/docusaurus-plugin-content-docs/current/cookbook/stacks-js-sending-transactions.md @@ -0,0 +1,55 @@ +--- +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. From 83258bb77099bdd43663844936919c51324d2823 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:43:33 +0100 Subject: [PATCH 0407/1444] New translations _category_.json (Russian) --- .../current/clarity/noteworthy-contracts/_category_.json | 8 ++++++++ 1 file changed, 8 insertions(+) create mode 100644 i18n/ru/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/_category_.json diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/_category_.json b/i18n/ru/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/_category_.json new file mode 100644 index 0000000000..f5de305558 --- /dev/null +++ b/i18n/ru/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/_category_.json @@ -0,0 +1,8 @@ +{ + "label": "Noteworthy Contracts", + "position": 4, + "link": { + "type": "generated-index", + "description": "Specific deployed Clarity Contracts worth mentioning." + } +} \ No newline at end of file From d832260988d0f57ae795b83f4d5450de3df3d3de Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:43:34 +0100 Subject: [PATCH 0408/1444] New translations bns-contract.md (Russian) --- .../noteworthy-contracts/bns-contract.md | 519 ++++++++++++++++++ 1 file changed, 519 insertions(+) create mode 100644 i18n/ru/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/bns-contract.md diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/bns-contract.md b/i18n/ru/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/bns-contract.md new file mode 100644 index 0000000000..a7770b7d24 --- /dev/null +++ b/i18n/ru/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/bns-contract.md @@ -0,0 +1,519 @@ +--- +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 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` From e507432d559fac2508e782855491d30fab3be240 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:43:35 +0100 Subject: [PATCH 0409/1444] New translations xbtc.md (Russian) --- .../clarity/noteworthy-contracts/xbtc.md | 28 +++++++++++++++++++ 1 file changed, 28 insertions(+) create mode 100644 i18n/ru/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/xbtc.md diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/xbtc.md b/i18n/ru/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/xbtc.md new file mode 100644 index 0000000000..e535dcf260 --- /dev/null +++ b/i18n/ru/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/xbtc.md @@ -0,0 +1,28 @@ +--- +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) From 294943b9cb766e06197a2870abc075581e4d36d5 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:43:36 +0100 Subject: [PATCH 0410/1444] New translations index.md (Russian) --- .../current/glossary/index.md | 284 ++++++++++++++++++ 1 file changed, 284 insertions(+) create mode 100644 i18n/ru/docusaurus-plugin-content-docs/current/glossary/index.md diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/glossary/index.md b/i18n/ru/docusaurus-plugin-content-docs/current/glossary/index.md new file mode 100644 index 0000000000..419c0e0d73 --- /dev/null +++ b/i18n/ru/docusaurus-plugin-content-docs/current/glossary/index.md @@ -0,0 +1,284 @@ +--- +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. From ed0b5efc3fea0d44a73f727a06d55ac82493252a Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:43:36 +0100 Subject: [PATCH 0411/1444] New translations quicknode.md (Russian) --- .../current/nodes-and-miners/quicknode.md | 45 +++++++++++++++++++ 1 file changed, 45 insertions(+) create mode 100644 i18n/ru/docusaurus-plugin-content-docs/current/nodes-and-miners/quicknode.md diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/nodes-and-miners/quicknode.md b/i18n/ru/docusaurus-plugin-content-docs/current/nodes-and-miners/quicknode.md new file mode 100644 index 0000000000..1281964689 --- /dev/null +++ b/i18n/ru/docusaurus-plugin-content-docs/current/nodes-and-miners/quicknode.md @@ -0,0 +1,45 @@ +--- +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. From a0a5211f2789bb59ffd8f3951b26abcd9815e6ed Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:43:37 +0100 Subject: [PATCH 0412/1444] New translations defi.md (Russian) --- .../current/services-using-stacks/defi.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) 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 index 51defacba7..58717a3234 100644 --- 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 @@ -26,7 +26,7 @@ Please edit this page to add any relevant new site that we are missing. ## Lnswap -[LNSWAP](https://www.lnswap.org). Non custiodial crypto currency exchange +[LNSWAP](https://www.lnswap.org). Non-custodial crypto currency exchange ![](/img/sh_lnswap.png) @@ -41,4 +41,3 @@ Please edit this page to add any relevant new site that we are missing. [Stackswap](https://app.stackswap.org/v2) ![](/img/sh_stackswap.png) - From 0673302cbc823b554dbcf61aa73a92d7424d5491 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:43:38 +0100 Subject: [PATCH 0413/1444] New translations more.md (Russian) --- .../current/services-using-stacks/more.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) 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 index df0b3e2254..1e14b9a5a5 100644 --- 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 @@ -18,6 +18,6 @@ Please edit this page to add any relevant new site that we are missing. ## Sigle -[Sigle](https://www.sigle.io/) is a decentralised and open source web 3 writing platform. +[Sigle](https://www.sigle.io/) is a decentralized and open source web 3 writing platform. -![](/img/sh_sigle.png) \ No newline at end of file +![](/img/sh_sigle.png) From c02390bdd9f3474796e15f3285e694613f95c5e9 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:43:39 +0100 Subject: [PATCH 0414/1444] New translations nft.md (Russian) --- .../current/services-using-stacks/nft.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) 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 index abb770663c..d582604854 100644 --- 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 @@ -15,6 +15,7 @@ Please edit this page to add any relevant new site that we are missing. ![website-screenshot](/img/sh_nft_byzantion.png) ### [Gamma](https://gamma.io/) + ![website-screenshot](/img/sh_nft_gamma.png) ### [Megapont](https://www.megapont.com/) @@ -35,4 +36,4 @@ Please edit this page to add any relevant new site that we are missing. ### [Superfandom](https://superfandom.io/) -![website-screenshot](/img/sh_superfandom.png) \ No newline at end of file +![website-screenshot](/img/sh_superfandom.png) From 311aa099767e89827f5f1e29fd377b0940928bae Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:43:40 +0100 Subject: [PATCH 0415/1444] New translations stacks-info-sites.md (Russian) --- .../current/services-using-stacks/stacks-info-sites.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) 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 index 35ced8dac6..54f6823e33 100644 --- 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 @@ -30,7 +30,7 @@ Please edit this page to add any relevant new site that we are missing. ![website-screenshot](/img/sh_stxstats.png) -### [Novuminsights](https://stacks.novuminsights.com/health) +### [Novum Insights](https://stacks.novuminsights.com/health) ![website-screenshot](/img/sh_novuminsights.png) From 5f29122c871d9252f323d1efcb243e739c6359db Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:43:40 +0100 Subject: [PATCH 0416/1444] New translations wallets.md (Russian) --- .../current/services-using-stacks/wallets.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) 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 index e5ea6c5b45..2d3fcc85f2 100644 --- 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 @@ -15,6 +15,7 @@ Please edit this page to add any relevant new site that we are missing. [Blockchain.com](https://www.blockchain.com/wallet) ![](/img/sh_blockchain.png) + ## Boom [Boom](https://boom.money) @@ -26,6 +27,7 @@ Please edit this page to add any relevant new site that we are missing. [D'CENT](https://dcentwallet.com) ![](/img/sh_dcent.png) + ## Hiro Wallet [Hiro Wallet](https://www.hiro.so/wallet) @@ -48,4 +50,4 @@ Please edit this page to add any relevant new site that we are missing. [Wise](https://wiseapp.id) -![](/img/sh_wiseapp.png) \ No newline at end of file +![](/img/sh_wiseapp.png) From bb6c4332a20a4ddbf3508128a5560bf11aa169b0 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:43:41 +0100 Subject: [PATCH 0417/1444] New translations whitepapers.md (Russian) --- .../current/stacks-academy/whitepapers.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) create mode 100644 i18n/ru/docusaurus-plugin-content-docs/current/stacks-academy/whitepapers.md diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/stacks-academy/whitepapers.md b/i18n/ru/docusaurus-plugin-content-docs/current/stacks-academy/whitepapers.md new file mode 100644 index 0000000000..0e564fbf44 --- /dev/null +++ b/i18n/ru/docusaurus-plugin-content-docs/current/stacks-academy/whitepapers.md @@ -0,0 +1,12 @@ +--- +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) From 46f1e625f7fbc0d869a49bb3e70d4b7da4d30783 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:43:42 +0100 Subject: [PATCH 0418/1444] New translations stacking-contract.md (Russian) --- .../noteworthy-contracts/stacking-contract.md | 352 ++++++++++++++++++ 1 file changed, 352 insertions(+) create mode 100644 i18n/ru/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/stacking-contract.md diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/stacking-contract.md b/i18n/ru/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/stacking-contract.md new file mode 100644 index 0000000000..c0027256cd --- /dev/null +++ b/i18n/ru/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/stacking-contract.md @@ -0,0 +1,352 @@ +--- +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. 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` From f9bf27b96f873343d7e1fbd71b70c8fb140a11d8 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:43:43 +0100 Subject: [PATCH 0419/1444] New translations index.md (Russian) --- .../current/next-steps/index.md | 39 +++++++++++++++++++ 1 file changed, 39 insertions(+) create mode 100644 i18n/ru/docusaurus-plugin-content-docs/current/next-steps/index.md diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/next-steps/index.md b/i18n/ru/docusaurus-plugin-content-docs/current/next-steps/index.md new file mode 100644 index 0000000000..00ddec9178 --- /dev/null +++ b/i18n/ru/docusaurus-plugin-content-docs/current/next-steps/index.md @@ -0,0 +1,39 @@ +--- +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) From 926a258a05e464921af3744064d3f974d5b0c3b7 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:43:44 +0100 Subject: [PATCH 0420/1444] New translations sips.md (Russian) --- .../current/stacks-academy/sips.md | 52 +++++++++++++++++++ 1 file changed, 52 insertions(+) create mode 100644 i18n/ru/docusaurus-plugin-content-docs/current/stacks-academy/sips.md diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/stacks-academy/sips.md b/i18n/ru/docusaurus-plugin-content-docs/current/stacks-academy/sips.md new file mode 100644 index 0000000000..aa2db18e62 --- /dev/null +++ b/i18n/ru/docusaurus-plugin-content-docs/current/stacks-academy/sips.md @@ -0,0 +1,52 @@ +--- +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/IJ15791776) 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-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. From e1d64937b312dc7c20a93a97fcac7703736e8435 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:43:45 +0100 Subject: [PATCH 0421/1444] New translations hosted-nodes.md (Russian) --- .../current/nodes-and-miners/hosted-nodes.md | 25 +++++++++++++++++++ 1 file changed, 25 insertions(+) create mode 100644 i18n/ru/docusaurus-plugin-content-docs/current/nodes-and-miners/hosted-nodes.md diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/nodes-and-miners/hosted-nodes.md b/i18n/ru/docusaurus-plugin-content-docs/current/nodes-and-miners/hosted-nodes.md new file mode 100644 index 0000000000..12d86c7ee2 --- /dev/null +++ b/i18n/ru/docusaurus-plugin-content-docs/current/nodes-and-miners/hosted-nodes.md @@ -0,0 +1,25 @@ +--- +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. From 66e1404d663de187d88ee67842c872b522f87586 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:43:45 +0100 Subject: [PATCH 0422/1444] New translations authentication.md (Turkish) --- .../current/stacks-academy/authentication.md | 63 +++++++++++++++++++ 1 file changed, 63 insertions(+) create mode 100644 i18n/tr/docusaurus-plugin-content-docs/current/stacks-academy/authentication.md diff --git a/i18n/tr/docusaurus-plugin-content-docs/current/stacks-academy/authentication.md b/i18n/tr/docusaurus-plugin-content-docs/current/stacks-academy/authentication.md new file mode 100644 index 0000000000..8152a401f9 --- /dev/null +++ b/i18n/tr/docusaurus-plugin-content-docs/current/stacks-academy/authentication.md @@ -0,0 +1,63 @@ +--- +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/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. From b2e1e53e3f52f61538c366426e62d77701d16ff4 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:43:46 +0100 Subject: [PATCH 0423/1444] New translations bns.md (Turkish) --- .../current/stacks-academy/bns.md | 242 ++++++++++++++++++ 1 file changed, 242 insertions(+) create mode 100644 i18n/tr/docusaurus-plugin-content-docs/current/stacks-academy/bns.md diff --git a/i18n/tr/docusaurus-plugin-content-docs/current/stacks-academy/bns.md b/i18n/tr/docusaurus-plugin-content-docs/current/stacks-academy/bns.md new file mode 100644 index 0000000000..4c89d9e56c --- /dev/null +++ b/i18n/tr/docusaurus-plugin-content-docs/current/stacks-academy/bns.md @@ -0,0 +1,242 @@ +--- +title: Blockchain Naming System +description: Binds Stacks usernames to off-chain state +sidebar_position: 8 +--- + +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 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). From 28e2efe77f958f6358a88f1778ae310f3d18b60f Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:43:47 +0100 Subject: [PATCH 0424/1444] New translations docs.md (Turkish) --- .../current/contribute/docs.md | 24 ++++++++++++------- 1 file changed, 15 insertions(+), 9 deletions(-) diff --git a/i18n/tr/docusaurus-plugin-content-docs/current/contribute/docs.md b/i18n/tr/docusaurus-plugin-content-docs/current/contribute/docs.md index 77705451b8..b2fef628f9 100644 --- a/i18n/tr/docusaurus-plugin-content-docs/current/contribute/docs.md +++ b/i18n/tr/docusaurus-plugin-content-docs/current/contribute/docs.md @@ -7,7 +7,7 @@ description: Learn how this site is built, and how you can contribute to it. 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). +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/). @@ -15,7 +15,7 @@ Don't want to learn it? No need to. Write [in plain text an issue on Github](htt :::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 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). @@ -24,28 +24,32 @@ To add new content, they are two different ways to do it, the [easy way](#easy-w [**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. +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 yourhanges in real time. + - `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. -## Aditional information +## 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 ``` @@ -54,8 +58,8 @@ Before running this command for the first time you will need to run `npm install 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 ``` @@ -91,7 +95,7 @@ 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. +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 @@ -124,6 +128,7 @@ And execute prettier with the following command: npx prettier --write mynewfiletocheck.md ``` --> + ### 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. @@ -138,6 +143,7 @@ To write a code block, you need to wrap your code in ` ```language `, and end yo (define-public (get-counter) (ok (var-get counter))) ``` + ### Admonitions You can use the following admonitions to highlight content. @@ -204,4 +210,4 @@ Some **content** with _markdown_ `syntax`. Some **content** with _markdown_ `syntax`. -::: \ No newline at end of file +::: From 5fdb6fe70cbd968e043271f9cf998b1c4463340a Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:43:49 +0100 Subject: [PATCH 0425/1444] New translations translations.md (Turkish) --- .../current/contribute/translations.md | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/i18n/tr/docusaurus-plugin-content-docs/current/contribute/translations.md b/i18n/tr/docusaurus-plugin-content-docs/current/contribute/translations.md index bd9a452333..fe8f8c6027 100644 --- a/i18n/tr/docusaurus-plugin-content-docs/current/contribute/translations.md +++ b/i18n/tr/docusaurus-plugin-content-docs/current/contribute/translations.md @@ -1,25 +1,24 @@ --- title: Contribute with translations -description: Want to help tranlating these docs to your local language? +description: Want to help translating 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. +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 Crodin intead. +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 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 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) From f139b6865bf2a598d6a348e42352c27aa231bb15 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:43:51 +0100 Subject: [PATCH 0426/1444] New translations gaia-on-ec2.md (Turkish) --- .../current/gaia/gaia-on-ec2.md | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) 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 index 2067e7d57c..3f58ca5e68 100644 --- 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 @@ -26,9 +26,10 @@ Use a link in the table to launch the [CloudFormation](https://console.aws.amazo ### Step 2 - Setup stack using template -You need to configure the template with the appropiate values for your hub and domain it runs on. +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 ``` @@ -52,7 +53,7 @@ Specify the stack details and then click `Next`: ![Specify template](/img/cloudf | 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`. | +| 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 | @@ -93,7 +94,9 @@ ssh -i admin@ 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 +![](/img/cloudformation-gaia-template1-designer.png) From 663791fcc47a5106813aec9333f35752db7d4c65 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:43:52 +0100 Subject: [PATCH 0427/1444] New translations gaia.md (Turkish) --- .../current/gaia/gaia.md | 12 +++++++++--- 1 file changed, 9 insertions(+), 3 deletions(-) diff --git a/i18n/tr/docusaurus-plugin-content-docs/current/gaia/gaia.md b/i18n/tr/docusaurus-plugin-content-docs/current/gaia/gaia.md index 1070857350..f86a0d61dc 100644 --- a/i18n/tr/docusaurus-plugin-content-docs/current/gaia/gaia.md +++ b/i18n/tr/docusaurus-plugin-content-docs/current/gaia/gaia.md @@ -1,14 +1,20 @@ --- title: Gaia description: Decentralized storage architecture for off-chain data -sidebar_position: 5 +sidebar_position: 6 tags: - gaia --- ## Introduction -Apps built with the Stacks blockchain store off-chain data using a storage system called Gaia. +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. @@ -38,7 +44,7 @@ The Stacks blockchain stores only identity data. Data created by the actions of 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) +![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. From f97fc28c908cccf43c5fa0a4e5fceebe0ac909b9 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:43:53 +0100 Subject: [PATCH 0428/1444] New translations setup-linux.md (Turkish) --- .../current/gaia/setup-linux.md | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) 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 index db427f890a..2c0ca2b92e 100644 --- a/i18n/tr/docusaurus-plugin-content-docs/current/gaia/setup-linux.md +++ b/i18n/tr/docusaurus-plugin-content-docs/current/gaia/setup-linux.md @@ -1,6 +1,6 @@ --- 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. +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 @@ -19,8 +19,7 @@ This configuration will setup the following 4 docker containers: 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: +**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 @@ -48,8 +47,7 @@ chmod +x ${DESTINATION_DC}/docker-compose 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. +**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 From ea62edba6be6e3e96dc8e45a7a68cccf9e5887f7 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:43:54 +0100 Subject: [PATCH 0429/1444] New translations digitalocean.md (Turkish) --- .../current/nodes-and-miners/digitalocean.md | 41 +++++++++++-------- 1 file changed, 25 insertions(+), 16 deletions(-) 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 index dd7194f504..15df918d04 100644 --- 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 @@ -1,28 +1,30 @@ --- -title: Stacks on DigitalOcean +title: Run a Node with Digital Ocean description: A guide to setup Stacks on DigitalOcean -sidebar_position: 4 +sidebar_position: 2 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). +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`. +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 plan that meets the minimum requirements) and your prefered datacenter region. ![](/img/sh_digitalocean-choose-plan.png) +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 if your prefer. +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) @@ -46,41 +48,48 @@ Congratulations! You are now running the Stacks Blockchain. You can click on `Co ## 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). +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`. -Once the stacks blockchain starts to sync with peers, application ports will open and nginx port 80 will now start proxying requests. +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 v3.0.3 (master:cd0c8aef)", + "server_version": "stacks-blockchain-api v6.2.3 (master:77ab3ae2)", "status": "ready", "chain_tip": { - "block_height": 16220, - "block_hash": "0x3123fba9c0de6b569573494cf83c1d5d198a66bfd5f48ef97949b6bf11ba13be", - "index_block_hash": "0xeec960fbbd6186b4ccac85ce12adba72be497d881f81e077305c90955b51a6ae" + "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/README.md#quickstart). +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). -## API Creation +## 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 -curl -X POST -H 'Content-Type: application/json' \ +$ export TOKEN= +$ 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"}' \ + '{"name":"stacks-blockchain","region":"sfo2","size":"s-2vcpu-4gb","image":"stacksfoundation-stacksblockchain"}' \ "https://api.digitalocean.com/v2/droplets" ``` From e172e736029b25f60f710a0ce5103e83af1a2c48 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:43:55 +0100 Subject: [PATCH 0430/1444] New translations index.md (Turkish) --- .../current/nodes-and-miners/index.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) 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 index b6cbb9754a..e5f4f2c250 100644 --- 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 @@ -1,11 +1,11 @@ --- title: Nodes and Miners description: Nodes and Miners -sidebar_position: 7 +sidebar_position: 5 --- -Here are all the steps to run nodes and miners, both on mainnet and testnet. +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. -## What's a Stacks node? +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. -## What's a Stacks miner? +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. From c198e257832db15a6e7cabc9a9f0e2f64bb96864 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:43:56 +0100 Subject: [PATCH 0431/1444] New translations miner-mainnet.md (Turkish) --- .../current/nodes-and-miners/miner-mainnet.md | 301 +++++++----------- 1 file changed, 110 insertions(+), 191 deletions(-) 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 index 061f4a2511..5afd34c23f 100644 --- 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 @@ -1,166 +1,100 @@ --- title: Mine mainnet Stacks tokens -description: Set up and run a miner on the Stacks 2.0 mainnet -sidebar_position: 5 +description: Set up and run a miner on Stacks Mainnet +sidebar_position: 6 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. +For more on the technical details of mining, please review the [mining guide](../stacks-academy/mining) -If you're interested in mining on the testnet, you can find instructions on how to do that [here](miner-testnet): +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 want to learn more about the technical details of mining, please review the [mining guide](../understand-stacks/mining): +If you're interested in mining on the Stacks testnet, you can find instructions on how to do that [here](miner-testnet): -## Running bitcoind locally +## Running a Bitcoin Mainnet Full Node -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) +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. -First, download the bitcoind software for your platform from https://bitcoin.org/en/download. +- [Ensure your computer meets the minimum hardware requirements before continuing.](https://bitcoin.org/en/bitcoin-core/features/requirements#system-requirements) -Next, start bitcoind with the following configuration: +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): -```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 -``` +:::tip It is recommened to use a persistent location for the chainstate, in the steps below we're using `/bitcoin` ::: -Finally, start bitcoind as follows: +### Update the Bitcoin Configuration File -```bash -bitcoind -conf=path/to/bitcoin.conf -``` - -It may take a few days for the node to synchronize with the Bitcoin mainnet. +Next, update the bitcoin configuration: -## 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: +- **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 -[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 = "" -... +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 ``` -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. +### Start Bitcoin -To run your miner, run this in the command line: +Finally, start bitcoin as follows (adjust the `conf` path to where it was created in the previous step, i.e. `$HOME/bitcoin.conf`): ```bash -stacks-node start --config=./testnet/stacks-node/conf/mainnet-miner-conf.toml +bitcoind -conf=$HOME/bitcoin.conf ``` -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 -``` +:::note +It will take a few days for the node to synchronize with Bitcoin mainnet. +::: -The above code will compile an optimized binary. To use it, run: +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 -cd ../.. -./target/release/stacks-node start --config=./mainnet-miner-conf.toml +$ bitcoin-cli \ + -rpcconnect=localhost \ + -rpcport=8332 \ + -rpcuser=btcuser \ + -rpcpassword=btcpassword \ +getblockchaininfo | jq .blocks +773281 ``` -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 Stacks Blockchain miner -## Running a miner in Windows +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) -### Prerequisites +_There may be some extra requirements to building, [defined here](https://github.com/stacksfoundation/miner-docs/blob/main/prerequisites.md#install-required-packages)_ -Make sure are [running a node](run-a-node) and [running bitcoind locally](#running-bitcoind-locally) before starting this tutorial. +:::tip It is recommened to use a persistent location for the chainstate, in the steps below we're using `/stacks-blockchain` ::: -### Generate keychain and get mainnet tokens in Windows +### Generate a keychain -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 cryptocurrency 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: +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 -npm install --global @stacks/cli -stx make_keychain > cli_keychain.json -type cli_keychain.json +npx @stacks/cli make_keychain 2>/dev/null | jq -r ``` -After this runs, you'll probably see some installation logs, and at the end you should see some JSON that looks like this: +After this runs, you should see some JSON printed to the screen that looks like this: ```json { @@ -174,109 +108,99 @@ After this runs, you'll probably see some installation logs, and at the end you } ``` -:::tip Check out the [Stacks CLI reference](https://docs.hiro.so/references/stacks-cli) for more details ::: +:::warning **Do not lose this information** - we'll need to use the `privateKey` and `btcAddress` fields in later steps. ::: -The above BTC address will then need to be imported into the BTC network. +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=your-user -rpcpassword=your-password importaddress +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 configuration file + + +### Update the Stacks Blockchain 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). +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`. -Update the following properties: +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] -... -# Enter your private key here -seed = "replace-with-your-private-key" -local_peer_seed = "replace-with-your-private-key" -... +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] -... -# To mine on mainnet, you need to run bitcoind locally -# Details can be found in above section, 'Running bitcoind locally' +chain = "bitcoin" +mode = "mainnet" peer_host = "127.0.0.1" -username = "" -password = "" -... +username = "" +password = "" +rpc_port = 8332 +peer_port = 8333 +satoshis_per_byte = 100 +burn_fee_cap = 20000 ``` -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 +### Start the Stacks Blockchain -To start your miner, run this in the command line: +To run your miner, run this in the command line: ```bash -stacks-node start --config=testnet/stacks-node/conf/mainnet-miner-conf.toml +stacks-node start --config=$HOME/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 +### 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 -set RUST_BACKTRACE=full; -set STACKS_LOG_DEBUG=1; -stacks-node start --config=mainnet-miner-conf.toml +STACKS_LOG_DEBUG=1 stacks-node start --config=$HOME/mainnet-miner-conf.toml ``` -## Optional: Running with Docker +--- + +## Optional: Running a Stacks Blockchain miner with Docker -Alternatively, you can run the mainnet node with Docker. +Alternatively, you can run a Stacks mainnet miner with Docker. -:::caution Ensure you have [Docker](https://docs.docker.com/get-docker/) installed on your machine. ::: +:::caution Ensure you have [Docker](https://docs.docker.com/get-docker/) installed. ::: -### Generate keychain and get tokens +### 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 +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 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: +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). -```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 = "" -... -``` +### Update Stacks Blockchain Docker Configuration File -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. +Use the steps oulined above to create the [configuration file](miner-mainnet#update-the-stacks-blockchain-configuration-file) -### Start the miner +### 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 ::: @@ -287,7 +211,8 @@ docker run -d \ --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" \ + -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 \ @@ -302,9 +227,9 @@ 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). +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 on your machine: +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) @@ -313,13 +238,7 @@ Ensure you have the following prerequisites installed on your machine: ### 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). +Use the steps [outlined above](miner-mainnet#generate-a-keychain-and-get-some-tokens) ### Install the chart and run the miner From 5fba5bb220dc8b36726b0bc2b97c283dd5877817 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:43:57 +0100 Subject: [PATCH 0432/1444] New translations miner-testnet.md (Turkish) --- .../current/nodes-and-miners/miner-testnet.md | 318 +++++++----------- 1 file changed, 130 insertions(+), 188 deletions(-) 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 index 56374190c1..c0a27e63d5 100644 --- 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 @@ -1,35 +1,52 @@ --- title: Mine testnet Stacks tokens -description: Set up and run a miner on the Stacks 2.0 testnet -sidebar_position: 4 +description: Set up and run a miner on Stacks Testnet +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 testnet. +For more on the technical details of mining, please review the [mining guide](../stacks-academy/mining) -If you want to learn more about the technical details of mining, please review the [mining guide](../understand-stacks/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)). -## Running bitcoind locally +If you're interested in mining on the Stacks mainnet, you can find instructions on how to do that [here](miner-mainnet): -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) +## Running a Bitcoin Testnet Full Node -First, download the bitcoind software for your platform from https://bitcoin.org/en/download. +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. -Next, start bitcoind with the following configuration: +- [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 -rpcuser=your-bitcoind-username -rpcpassword=your-bitcoind-password testnet=1 -txindex=0 -listen=1 -rpcserialversion=0 -maxorphantx=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 @@ -37,126 +54,51 @@ 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" -... +### Start Bitcoin -[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: +Finally, start bitcoind as follows: ```bash -stacks-node start --config=./testnet/stacks-node/conf/testnet-miner-conf.toml +bitcoind -conf=$HOME/bitcoin.conf ``` -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 -``` +:::note +It will take a few hours for the node to synchronize with Bitcoin testnet. +::: -The above code will compile an optimized binary. To use it, run: +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 -cd ../.. -./target/release/stacks-node start --config=./testnet/conf/testnet-follower-conf.toml +$ bitcoin-cli \ + -rpcconnect=localhost \ + -rpcport=18332 \ + -rpcuser=btcuser \ + -rpcpassword=btcpass \ +getblockchaininfo | jq .blocks +2417570 ``` -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 +## Running a Stacks Blockchain miner -### Prerequisites +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) -Make sure are [running a testnet node](run-a-node) before starting this tutorial. +_There may be some extra requirements to building, [defined here](https://github.com/stacksfoundation/miner-docs/blob/main/prerequisites.md#install-required-packages)_ -### Generate keychain and get testnet tokens in Windows +:::tip It is recommened to use a persistent location for the chainstate, in the steps below we're using `/stacks-blockchain` ::: -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. +### Generate a keychain -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. +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. -Generate a keychain: +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 -npm install --global @stacks/cli -stx make_keychain -t > cli_keychain.json -type cli_keychain.json +npx @stacks/cli make_keychain -t 2>/dev/null | jq -r ``` -After this runs, you'll probably see some installation logs, and at the end you should see some JSON that looks like this: +After this runs, you should see some JSON printed to the screen that looks like this: ```json { @@ -170,107 +112,110 @@ After this runs, you'll probably see some installation logs, and at the end you } ``` -:::tip Check out the [Stacks CLI reference](https://docs.hiro.so/references/stacks-cli) for more details ::: +:::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. -Request BTC from faucet: +### Update the Stacks Blockchain Configuration File -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/). +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`. -### Update configuration file +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. -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). +Next, update the bitcoin configuration: -Update the following properties: +- **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] -... -seed = "replace-with-your-private-key" -local_peer_seed = "replace-with-your-private-key" -... +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] -... -# To mine on Testnet, you need to run bitcoind locally -# Details can be found in above section, 'Running bitcoind locally' +chain = "bitcoin" +mode = "xenon" peer_host = "127.0.0.1" -username = "" -password = "" -... +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 ``` -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 +### Start the Stacks Blockchain -To start your miner, run this in the command line: +To run your miner, run this in the command line: ```bash -stacks-node start --config=testnet/stacks-node/conf/testnet-miner-conf.toml +stacks-node start --config=$HOME/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 +### 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 -set RUST_BACKTRACE=full; -set STACKS_LOG_DEBUG=1; -stacks-node start --config=testnet-miner-conf.toml +STACKS_LOG_DEBUG=1 stacks-node start --config=$HOME/testnet-miner-conf.toml ``` -## Optional: Running with Docker +--- + +## Optional: Running a Stacks Blockchain miner with Docker -Alternatively, you can run the testnet node with Docker. +Alternatively, you can run a Stacks testnet miner with Docker. -:::warning Ensure you have [Docker](https://docs.docker.com/get-docker/) installed on your machine. ::: +:::caution Ensure you have [Docker](https://docs.docker.com/get-docker/) installed ::: -### Generate keychain and get testnet tokens +### Generate a Keychain and Get Some Tokens Generate a keychain: ```bash -docker run -i node:14-alpine npx @stacks/cli make_keychain -t 2>/dev/null +docker run -i node:14-alpine npx @stacks/cli make_keychain 2>/dev/null | jq -r ``` -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 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. -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 Stacks Blockchain Docker Configuration File -Update the following properties: +Use the steps oulined above to create the [configuration file](miner-testnet#update-the-stacks-blockchain-configuration-file) -```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 +### 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 ::: @@ -281,7 +226,8 @@ docker run -d \ --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" \ + -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 \ @@ -294,26 +240,22 @@ You can review the node logs with this command: 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). +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 on your machine: +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 testnet tokens - -Generate a keychain: - -```bash -docker run -i node:14-alpine npx @stacks/cli make_keychain -t 2>/dev/null -``` +### Generate keychain and get some tokens -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/). +Use the steps [outlined above](miner-testnet#generate-a-keychain-and-get-some-tokens) ### Install the chart and run the miner @@ -324,7 +266,7 @@ 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.node.seed="replace-with-your-privateKey-from-generate-keychain-step" \ ``` You can review the node logs with this command: From c5aeb39f4938a944a742422ba34983fabf4f5219 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:43:58 +0100 Subject: [PATCH 0433/1444] New translations stacks-node-configuration.md (Turkish) --- .../stacks-node-configuration.md | 158 +++++++++++------- 1 file changed, 101 insertions(+), 57 deletions(-) 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 index 89af343dc6..cd216e7103 100644 --- 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 @@ -1,7 +1,7 @@ --- title: Stacks Node Configuration description: Configuration parameters and options for the stacks-node binary -sidebar_position: 6 +sidebar_position: 4 --- ## Usage @@ -10,97 +10,141 @@ sidebar_position: 6 stacks-node sub-command [--subcommand-option ] ``` -## Subcommands +### 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 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 -### mocknet +## Configuration File Options -Start a node based on a fast local setup emulating a burnchain. Ideal for smart contract development. +The Stacks Blockchain configuration file has multiple sections under which an option may be placed. -Example: +- [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) -```bash -stacks-node mocknet -``` +For reference, several configuration file examples are [available here](https://github.com/stacks-network/stacks-blockchain/tree/master/testnet/stacks-node/conf) -### krypton +- [Example mainnet follower configuration](./stacks-node-configuration#example-mainnet-follower-configuration) -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). +### node -Example: +Contains various configuration options for the stacks-node binary. -```bash -stacks-node krypton -``` +| 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. | -### testnet +### events_observer -Start a node that will join and stream blocks from the public testnet. +:::info This section is _optional_ and not required -Example: +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. -```bash -stacks-node testnet -``` +| 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. | | -### mainnet +### connection_options -Start a node that joins and streams blocks from the public mainnet. +:::info This section is _optional_ and not required. -Example: +However, if this section is added, **all** fields are required ::: -```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. +Specifies configuration options for others connecting to the stacks node. -#### Arguments +| 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 | -**--config**: relative or absolute path to the TOML config file. Required. +### burnchain -Example: +This section contains configuration options pertaining to the blockchain the stacks-node binds to on the backend for proof-of-transfer (BTC). -```bash -stacks-node start --config=/path/to/config.toml -``` +| 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` | -See [Configuration File Options](#configuration-file-options) for more information. +#### Mining -#### version +| 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`. | -Displays information about the current version and the release cycle. +### ustx_balance -Example: +- `mocknet`/`testnet` only -```bash -stacks-node version -``` +This section contains configuration options allocating microSTX per address in the genesis block -#### help +This section can repeat multiple times, but each section can only define a single address. -Displays a help message. +:::info This section is only required for the `testnet` and `mocknet` networks. -Example: +However, if this section is added, **all** fields are required ::: -```bash -stacks-node help -``` +| 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 | -## Configuration File Options +## Example Mainnet Follower Configuration -The TOML configuration file has multiple sections under which an option may be placed. +```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" -To see a list of example configurations, [please see this page](https://github.com/stacks-network/stacks-blockchain/tree/master/testnet/stacks-node/conf). +[burnchain] +chain = "bitcoin" +mode = "mainnet" +peer_host = "localhost" +username = "user" +password = "pass" +rpc_port = 8332 +peer_port = 8333 -### Section: node +[[events_observer]] +endpoint = "localhost:3700" +retry_count = 255 +events_keys = ["*"] +``` -Contains various configuration options pertaining to the stacks-node. -Example: + From 9a40c2451091d17fd526c5062069ed89ead20eea Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:43:59 +0100 Subject: [PATCH 0434/1444] New translations accounts.md (Turkish) --- .../current/stacks-academy/accounts.md | 215 ++++++++++++++++++ 1 file changed, 215 insertions(+) create mode 100644 i18n/tr/docusaurus-plugin-content-docs/current/stacks-academy/accounts.md diff --git a/i18n/tr/docusaurus-plugin-content-docs/current/stacks-academy/accounts.md b/i18n/tr/docusaurus-plugin-content-docs/current/stacks-academy/accounts.md new file mode 100644 index 0000000000..55d0165def --- /dev/null +++ b/i18n/tr/docusaurus-plugin-content-docs/current/stacks-academy/accounts.md @@ -0,0 +1,215 @@ +--- +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" + } + } + ] +} +``` From 39f744ccbcd2fea8b2ca1ad1359f3b8b03bbef43 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:43:59 +0100 Subject: [PATCH 0435/1444] New translations microblocks.md (Turkish) --- .../current/stacks-academy/microblocks.md | 107 ++++++++++++++++++ 1 file changed, 107 insertions(+) create mode 100644 i18n/tr/docusaurus-plugin-content-docs/current/stacks-academy/microblocks.md diff --git a/i18n/tr/docusaurus-plugin-content-docs/current/stacks-academy/microblocks.md b/i18n/tr/docusaurus-plugin-content-docs/current/stacks-academy/microblocks.md new file mode 100644 index 0000000000..9310aa65be --- /dev/null +++ b/i18n/tr/docusaurus-plugin-content-docs/current/stacks-academy/microblocks.md @@ -0,0 +1,107 @@ +--- +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. + +[provides an endpoint]: https://docs.hiro.so/get-started/stacks-blockchain-api#nonce-handling +[microblocks_api]: https://docs.hiro.so/api#tag/Microblocks From eadd0e59863296774f58fc3beda9920992edec0b Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:44:00 +0100 Subject: [PATCH 0436/1444] New translations mining.md (Turkish) --- .../current/stacks-academy/mining.md | 84 +++++++++++++++++++ 1 file changed, 84 insertions(+) create mode 100644 i18n/tr/docusaurus-plugin-content-docs/current/stacks-academy/mining.md diff --git a/i18n/tr/docusaurus-plugin-content-docs/current/stacks-academy/mining.md b/i18n/tr/docusaurus-plugin-content-docs/current/stacks-academy/mining.md new file mode 100644 index 0000000000..e6e93e130a --- /dev/null +++ b/i18n/tr/docusaurus-plugin-content-docs/current/stacks-academy/mining.md @@ -0,0 +1,84 @@ +--- +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 From 4e7dd0ecabafe3443be0c8882f5ede9eb3b87d4c Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:44:01 +0100 Subject: [PATCH 0437/1444] New translations network.md (Turkish) --- .../current/stacks-academy/network.md | 148 ++++++++++++++++++ 1 file changed, 148 insertions(+) create mode 100644 i18n/tr/docusaurus-plugin-content-docs/current/stacks-academy/network.md diff --git a/i18n/tr/docusaurus-plugin-content-docs/current/stacks-academy/network.md b/i18n/tr/docusaurus-plugin-content-docs/current/stacks-academy/network.md new file mode 100644 index 0000000000..a0dc623d97 --- /dev/null +++ b/i18n/tr/docusaurus-plugin-content-docs/current/stacks-academy/network.md @@ -0,0 +1,148 @@ +--- +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 +} +``` From fb045a1fbb5f7e0b22e1266ef8ce5d561c9ff260 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:44:02 +0100 Subject: [PATCH 0438/1444] New translations stacking.md (Turkish) --- .../current/stacks-academy/stacking.md | 151 ++++++++++++++++++ 1 file changed, 151 insertions(+) create mode 100644 i18n/tr/docusaurus-plugin-content-docs/current/stacks-academy/stacking.md diff --git a/i18n/tr/docusaurus-plugin-content-docs/current/stacks-academy/stacking.md b/i18n/tr/docusaurus-plugin-content-docs/current/stacks-academy/stacking.md new file mode 100644 index 0000000000..545f538ecb --- /dev/null +++ b/i18n/tr/docusaurus-plugin-content-docs/current/stacks-academy/stacking.md @@ -0,0 +1,151 @@ +--- +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. 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. + +![](/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 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 (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 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) From 8b2d8ffddcaaef54fe2e0144bef7f4f40a6fbaad Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:44:03 +0100 Subject: [PATCH 0439/1444] New translations technical-specs.md (Turkish) --- .../current/stacks-academy/technical-specs.md | 79 +++++++++++++++++++ 1 file changed, 79 insertions(+) create mode 100644 i18n/tr/docusaurus-plugin-content-docs/current/stacks-academy/technical-specs.md diff --git a/i18n/tr/docusaurus-plugin-content-docs/current/stacks-academy/technical-specs.md b/i18n/tr/docusaurus-plugin-content-docs/current/stacks-academy/technical-specs.md new file mode 100644 index 0000000000..695f849e1a --- /dev/null +++ b/i18n/tr/docusaurus-plugin-content-docs/current/stacks-academy/technical-specs.md @@ -0,0 +1,79 @@ +--- +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). +- 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 whitepaper v2](https://www.youtube.com/watch?v=Wd-Bfe8Sn-Y). From a1f526f2199b588001a878f7404a6dd5022bde47 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:44:04 +0100 Subject: [PATCH 0440/1444] New translations testnet.md (Turkish) --- .../current/stacks-academy/testnet.md | 35 +++++++++++++++++++ 1 file changed, 35 insertions(+) create mode 100644 i18n/tr/docusaurus-plugin-content-docs/current/stacks-academy/testnet.md diff --git a/i18n/tr/docusaurus-plugin-content-docs/current/stacks-academy/testnet.md b/i18n/tr/docusaurus-plugin-content-docs/current/stacks-academy/testnet.md new file mode 100644 index 0000000000..f8b9f03df2 --- /dev/null +++ b/i18n/tr/docusaurus-plugin-content-docs/current/stacks-academy/testnet.md @@ -0,0 +1,35 @@ +--- +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. + +### 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) From 7a009739ef4b42c10cbf5e4f722c11cb6d2e11b9 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:44:04 +0100 Subject: [PATCH 0441/1444] New translations transactions.md (Turkish) --- .../current/stacks-academy/transactions.md | 40 +++++++++++++++++++ 1 file changed, 40 insertions(+) create mode 100644 i18n/tr/docusaurus-plugin-content-docs/current/stacks-academy/transactions.md diff --git a/i18n/tr/docusaurus-plugin-content-docs/current/stacks-academy/transactions.md b/i18n/tr/docusaurus-plugin-content-docs/current/stacks-academy/transactions.md new file mode 100644 index 0000000000..ba6b18f0f7 --- /dev/null +++ b/i18n/tr/docusaurus-plugin-content-docs/current/stacks-academy/transactions.md @@ -0,0 +1,40 @@ +--- +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). ::: From b2518975283ca02093634f2d260a7c5dbb6f7f41 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:44:06 +0100 Subject: [PATCH 0442/1444] New translations language-functions.md (Turkish) --- .../current/clarity/language-functions.md | 2031 +++++++++++++++++ 1 file changed, 2031 insertions(+) create mode 100644 i18n/tr/docusaurus-plugin-content-docs/current/clarity/language-functions.md diff --git a/i18n/tr/docusaurus-plugin-content-docs/current/clarity/language-functions.md b/i18n/tr/docusaurus-plugin-content-docs/current/clarity/language-functions.md new file mode 100644 index 0000000000..0325c1ac40 --- /dev/null +++ b/i18n/tr/docusaurus-plugin-content-docs/current/clarity/language-functions.md @@ -0,0 +1,2031 @@ +--- +title: Functions +description: See a detailed list of all functions for the Clarity language. +sidebar_position: 3 +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: + +#### 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-existent\"))))) ;; 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-existent\") ;; 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-existent\" })) ;; 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-existent\" }))) ;; 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-existent\" }))) ;; 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 \"Stacks\" '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 successfully 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_ transferred from another principal, but rather minted. + +If a non-positive amount is provided to mint, this function returns `(err 1)`. Otherwise, on successfully 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_ transferred 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 successfully 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 successfully 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)) +``` From 1bca84aa673754748c7dcd693bbb5eb650b1fe0f Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:44:07 +0100 Subject: [PATCH 0443/1444] New translations language-keywords.md (Turkish) --- .../current/clarity/language-keywords.md | 146 ++++++++++++++++++ 1 file changed, 146 insertions(+) create mode 100644 i18n/tr/docusaurus-plugin-content-docs/current/clarity/language-keywords.md diff --git a/i18n/tr/docusaurus-plugin-content-docs/current/clarity/language-keywords.md b/i18n/tr/docusaurus-plugin-content-docs/current/clarity/language-keywords.md new file mode 100644 index 0000000000..1aca5359c3 --- /dev/null +++ b/i18n/tr/docusaurus-plugin-content-docs/current/clarity/language-keywords.md @@ -0,0 +1,146 @@ +--- +title: Keywords +description: See a detailed list of all keywords for the Clarity language. +sidebar_position: 4 +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 +``` From d8af92fd58ec9991d42759694d95e762a9faada2 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:44:08 +0100 Subject: [PATCH 0444/1444] New translations language-types.md (Turkish) --- .../current/clarity/language-types.md | 25 +++++++++++++++++++ 1 file changed, 25 insertions(+) create mode 100644 i18n/tr/docusaurus-plugin-content-docs/current/clarity/language-types.md diff --git a/i18n/tr/docusaurus-plugin-content-docs/current/clarity/language-types.md b/i18n/tr/docusaurus-plugin-content-docs/current/clarity/language-types.md new file mode 100644 index 0000000000..0af4577dc9 --- /dev/null +++ b/i18n/tr/docusaurus-plugin-content-docs/current/clarity/language-types.md @@ -0,0 +1,25 @@ +--- +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. | From 898f93ab0d60c7b2ebde454b6a575683926260a4 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:44:10 +0100 Subject: [PATCH 0445/1444] New translations miner-costs-and-fees.md (Turkish) --- .../current/nodes-and-miners/miner-costs-and-fees.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) 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 index 40397a51e0..dd8ee721cc 100644 --- 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 @@ -8,7 +8,7 @@ sidebar_position: 8 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 @@ -22,3 +22,5 @@ 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). From b8b7e74f65974b0374b175005752054a28934a81 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:44:11 +0100 Subject: [PATCH 0446/1444] New translations verify-miner.md (Turkish) --- .../current/nodes-and-miners/verify-miner.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) 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 index 094e3f03a1..18e8dd3a48 100644 --- 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 @@ -7,7 +7,7 @@ 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 +$ 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 -``` \ No newline at end of file +``` From 975acb688883b312e2470930200fd6ea37d696b9 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:44:11 +0100 Subject: [PATCH 0447/1444] New translations stacks-blockchain-api.md (Turkish) --- .../stacks-academy/stacks-blockchain-api.md | 41 +++++++++++++++++++ 1 file changed, 41 insertions(+) create mode 100644 i18n/tr/docusaurus-plugin-content-docs/current/stacks-academy/stacks-blockchain-api.md diff --git a/i18n/tr/docusaurus-plugin-content-docs/current/stacks-academy/stacks-blockchain-api.md b/i18n/tr/docusaurus-plugin-content-docs/current/stacks-academy/stacks-blockchain-api.md new file mode 100644 index 0000000000..ad9bb1822e --- /dev/null +++ b/i18n/tr/docusaurus-plugin-content-docs/current/stacks-academy/stacks-blockchain-api.md @@ -0,0 +1,41 @@ +--- +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`. ::: From d1ffec5e1b1a31c2a7bffc615c7303b9f6113e34 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:44:12 +0100 Subject: [PATCH 0448/1444] New translations run-a-node.md (Turkish) --- .../current/nodes-and-miners/run-a-node.md | 329 +++--------------- 1 file changed, 42 insertions(+), 287 deletions(-) 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 index 94d938c5ca..2993568ce4 100644 --- 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 @@ -1,5 +1,5 @@ --- -title: Run a node +title: Run a Node with Docker description: Set up and run a Stacks node sidebar_position: 1 tags: @@ -8,344 +8,99 @@ tags: ## Stacks Blockchain with Docker -Run your own Stacks Blockchain node easily with just few commands. +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) -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](./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) -## **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 -``` +## **Requirements:** -- With optional proxy: +The **minimum viable requirements** are listed below. -```bash -./manage.sh -n -a start -f proxy -``` +While you _can_ run a node using these specs, it's _recommended_ to assign more than the minimum for better performance. -- With optional bitcoin node: +- ⚠️ [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_ ) -```bash -./manage.sh -n -a start -f bitcoin -``` +:::caution MacOS with an ARM processor is NOT recommended -5. **Stop the Services** +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. ::: -```bash -./manage.sh -n -a stop -``` - -6. **Retrieve Service Logs** - -```bash -./manage.sh -n -a logs -``` - -- Export docker log files to `./exported-logs`: +## **Quickstart** -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. +The `` placeholder used below can be replaced with one of: -```bash -./manage.sh -n -a logs export -``` +- mainnet +- testnet +- mocknet -7. **Restart all services** +1. **Clone the stacks-blockchain-docker repository locally** ```bash -./manage.sh -n -a restart +git clone https://github.com/stacks-network/stacks-blockchain-docker && cd stacks-blockchain-docker ``` -- With optional proxy: +2. **Start the Services** ```bash -./manage.sh -n -a restart -f proxy +./manage.sh -n -a start ``` -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. +:::note With an optional HTTP proxy on port 80: ```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. - +./manage.sh -n -a start -f proxy ``` -9. **Download BNS data to** `./persistent-data/bns-data` - -```bash -./manage.sh bns -``` +::: -10. **Export stacks-blockchain-api events** (_Not applicable for mocknet_) +## **Accessing the services** -```bash -./manage.sh -n -a export -# check logs for completion -./manage.sh -n -a restart -``` +:::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. -11. **Replay stacks-blockchain-api events** (_Not applicable for mocknet_) +Follow the logs to track the sync progress: ```bash -./manage.sh -n -a import -# check logs for completion -./manage.sh -n -a restart +./manage.sh -n -a logs ``` -## **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` +- Ports `20443-20444` are exposed on `localhost` ```bash -curl -sL localhost:20443/v2/info | jq +curl -sL localhost:20443/v2/info | jq -r ``` **stacks-blockchain-api**: -- Port `3999` are exposed to `localhost` +- Port `3999` is exposed on `localhost` ```bash -curl -sL localhost:3999/v2/info | jq +curl -sL localhost:3999 | jq -r ``` **proxy**: -- Port `80` is exposed to `localhost` +- Port `80` is exposed on `localhost` ```bash -curl -sL localhost/v2/info | jq -curl -sL localhost/ | jq +curl -sL localhost/v2/info | jq -r +curl -sL localhost | jq -r ``` --- ## 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 -``` +:::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): ::: --- - -## **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 From 66fe71478c95c9d05d029eaf41ca00200e0ca767 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:44:13 +0100 Subject: [PATCH 0449/1444] New translations index.md (Turkish) --- .../current/clarity/index.md | 58 +++++++++++++++++++ 1 file changed, 58 insertions(+) create mode 100644 i18n/tr/docusaurus-plugin-content-docs/current/clarity/index.md diff --git a/i18n/tr/docusaurus-plugin-content-docs/current/clarity/index.md b/i18n/tr/docusaurus-plugin-content-docs/current/clarity/index.md new file mode 100644 index 0000000000..903de93a45 --- /dev/null +++ b/i18n/tr/docusaurus-plugin-content-docs/current/clarity/index.md @@ -0,0 +1,58 @@ +--- +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?2 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. If you are unsure what this means, let it not worry you for now. The serious advantage of decidability will become more apparent over time. + +### 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. From 0cd37f369a3a2c67f81514182cad0f434965ccea Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:44:14 +0100 Subject: [PATCH 0450/1444] New translations index.md (Turkish) --- .../current/stacks-academy/index.md | 11 +++++++++++ 1 file changed, 11 insertions(+) create mode 100644 i18n/tr/docusaurus-plugin-content-docs/current/stacks-academy/index.md diff --git a/i18n/tr/docusaurus-plugin-content-docs/current/stacks-academy/index.md b/i18n/tr/docusaurus-plugin-content-docs/current/stacks-academy/index.md new file mode 100644 index 0000000000..a5bdb3c790 --- /dev/null +++ b/i18n/tr/docusaurus-plugin-content-docs/current/stacks-academy/index.md @@ -0,0 +1,11 @@ +--- +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. From 740a8ee3324b2e03b4f8ae2cd038c624cd955a19 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:44:15 +0100 Subject: [PATCH 0451/1444] New translations proof-of-transfer.md (Turkish) --- .../stacks-academy/proof-of-transfer.md | 83 +++++++++++++++++++ 1 file changed, 83 insertions(+) create mode 100644 i18n/tr/docusaurus-plugin-content-docs/current/stacks-academy/proof-of-transfer.md diff --git a/i18n/tr/docusaurus-plugin-content-docs/current/stacks-academy/proof-of-transfer.md b/i18n/tr/docusaurus-plugin-content-docs/current/stacks-academy/proof-of-transfer.md new file mode 100644 index 0000000000..50f4b739d6 --- /dev/null +++ b/i18n/tr/docusaurus-plugin-content-docs/current/stacks-academy/proof-of-transfer.md @@ -0,0 +1,83 @@ +--- +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. From d79666f3a9798d91c757a9aef06c60b53edb9323 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:44:15 +0100 Subject: [PATCH 0452/1444] New translations what-is-stacks.md (Turkish) --- .../current/stacks-academy/what-is-stacks.md | 102 ++++++++++++++++++ 1 file changed, 102 insertions(+) create mode 100644 i18n/tr/docusaurus-plugin-content-docs/current/stacks-academy/what-is-stacks.md diff --git a/i18n/tr/docusaurus-plugin-content-docs/current/stacks-academy/what-is-stacks.md b/i18n/tr/docusaurus-plugin-content-docs/current/stacks-academy/what-is-stacks.md new file mode 100644 index 0000000000..94277da8a9 --- /dev/null +++ b/i18n/tr/docusaurus-plugin-content-docs/current/stacks-academy/what-is-stacks.md @@ -0,0 +1,102 @@ +--- +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. + +There's a lot of jargon, possible assumptions, controversy, and cool technology wrapped up in those statements. So let's get started by getting a 30,000 foot view of what exactly Stacks is. + +## Stacks Explained in (Slightly Less Than) 10 Minutes + +
+ +
+ +## 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, Stacks takes a different approach. + +## 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). + +By taking this 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 with some unique properties, like having its own token, that allow it to maintain a historical ledger of all of its transactions and operate with its own security budget. + +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_. + +Nope. 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. From bda4761eeb6a45014bbcc7a99051bbafef49ec49 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:44:16 +0100 Subject: [PATCH 0453/1444] New translations community-tutorials.md (Turkish) --- .../current/tutorials/community-tutorials.md | 24 +++++++++++++++++++ 1 file changed, 24 insertions(+) create mode 100644 i18n/tr/docusaurus-plugin-content-docs/current/tutorials/community-tutorials.md diff --git a/i18n/tr/docusaurus-plugin-content-docs/current/tutorials/community-tutorials.md b/i18n/tr/docusaurus-plugin-content-docs/current/tutorials/community-tutorials.md new file mode 100644 index 0000000000..a4f3d970ca --- /dev/null +++ b/i18n/tr/docusaurus-plugin-content-docs/current/tutorials/community-tutorials.md @@ -0,0 +1,24 @@ +--- +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/) From 5de5335b458140405160d1831991e49324e2d5d0 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:44:17 +0100 Subject: [PATCH 0454/1444] New translations hello-stacks.md (Turkish) --- .../current/tutorials/hello-stacks.md | 759 ++++++++++++++++++ 1 file changed, 759 insertions(+) create mode 100644 i18n/tr/docusaurus-plugin-content-docs/current/tutorials/hello-stacks.md diff --git a/i18n/tr/docusaurus-plugin-content-docs/current/tutorials/hello-stacks.md b/i18n/tr/docusaurus-plugin-content-docs/current/tutorials/hello-stacks.md new file mode 100644 index 0000000000..a0a442d135 --- /dev/null +++ b/i18n/tr/docusaurus-plugin-content-docs/current/tutorials/hello-stacks.md @@ -0,0 +1,759 @@ +--- +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. From f177216635b9b62c7232863627125a771127ba96 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:44:18 +0100 Subject: [PATCH 0455/1444] New translations index.md (Turkish) --- .../current/tutorials/index.md | 11 +++++++++++ 1 file changed, 11 insertions(+) create mode 100644 i18n/tr/docusaurus-plugin-content-docs/current/tutorials/index.md diff --git a/i18n/tr/docusaurus-plugin-content-docs/current/tutorials/index.md b/i18n/tr/docusaurus-plugin-content-docs/current/tutorials/index.md new file mode 100644 index 0000000000..1d544c7bc1 --- /dev/null +++ b/i18n/tr/docusaurus-plugin-content-docs/current/tutorials/index.md @@ -0,0 +1,11 @@ +--- +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. From a436b6f0cf453dff89587b3e57d7032589c550a0 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:44:19 +0100 Subject: [PATCH 0456/1444] New translations satoshis-ridge.md (Turkish) --- .../current/tutorials/satoshis-ridge.md | 75 +++++++++++++++++++ 1 file changed, 75 insertions(+) create mode 100644 i18n/tr/docusaurus-plugin-content-docs/current/tutorials/satoshis-ridge.md diff --git a/i18n/tr/docusaurus-plugin-content-docs/current/tutorials/satoshis-ridge.md b/i18n/tr/docusaurus-plugin-content-docs/current/tutorials/satoshis-ridge.md new file mode 100644 index 0000000000..596339ae74 --- /dev/null +++ b/i18n/tr/docusaurus-plugin-content-docs/current/tutorials/satoshis-ridge.md @@ -0,0 +1,75 @@ +--- +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 arguable one of its strengths. + +Instead, we need to create separate layers that add additional functionality without modify 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. From 54cb7c3ef521c04482158f9b8b36bfaa132cc318 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:44:19 +0100 Subject: [PATCH 0457/1444] New translations crash-course.md (Turkish) --- .../current/clarity/crash-course.md | 122 ++++++++++++++++++ 1 file changed, 122 insertions(+) create mode 100644 i18n/tr/docusaurus-plugin-content-docs/current/clarity/crash-course.md diff --git a/i18n/tr/docusaurus-plugin-content-docs/current/clarity/crash-course.md b/i18n/tr/docusaurus-plugin-content-docs/current/clarity/crash-course.md new file mode 100644 index 0000000000..5b27a3c275 --- /dev/null +++ b/i18n/tr/docusaurus-plugin-content-docs/current/clarity/crash-course.md @@ -0,0 +1,122 @@ +--- +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.md). + +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. + +```clojure +(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: + +```clojure +(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. From 8f2c0d9c1067053257e6b9669061b85849d3c0ef Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:44:20 +0100 Subject: [PATCH 0458/1444] New translations sample-contracts.md (Turkish) --- .../current/clarity/sample-contracts.md | 14 ++++++++++++++ 1 file changed, 14 insertions(+) create mode 100644 i18n/tr/docusaurus-plugin-content-docs/current/clarity/sample-contracts.md diff --git a/i18n/tr/docusaurus-plugin-content-docs/current/clarity/sample-contracts.md b/i18n/tr/docusaurus-plugin-content-docs/current/clarity/sample-contracts.md new file mode 100644 index 0000000000..adb12a58fd --- /dev/null +++ b/i18n/tr/docusaurus-plugin-content-docs/current/clarity/sample-contracts.md @@ -0,0 +1,14 @@ +--- +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) From 4dd8c5f57236e4dcdeec641fa989ebc16b4477f2 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:44:21 +0100 Subject: [PATCH 0459/1444] New translations index.md (Turkish) --- .../current/cookbook/index.md | 64 +++++++++++++++++++ 1 file changed, 64 insertions(+) create mode 100644 i18n/tr/docusaurus-plugin-content-docs/current/cookbook/index.md diff --git a/i18n/tr/docusaurus-plugin-content-docs/current/cookbook/index.md b/i18n/tr/docusaurus-plugin-content-docs/current/cookbook/index.md new file mode 100644 index 0000000000..a2b0e42eea --- /dev/null +++ b/i18n/tr/docusaurus-plugin-content-docs/current/cookbook/index.md @@ -0,0 +1,64 @@ +--- +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 + +Swapping between Bitcoin and Stacks addresses + +Swapping between xBTC and BTC + +Verifying a transaction on the BTC chain + +## 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 + +Airdropping an NFT to a Bitcoin address + +## Stacking and Mining + +Simple stacking pool + +Continuous stacking + +Simple mining pool + +Proof of PoX payout + +## Oracles + +Creating a simple BTC price oracle + +## Frontend + +[Post conditions with Stacks.js](./post-conditions) + +[Authentication with Stacks.js](./stacks-js-auth) + +[Sending transactions with Stacks.js](./stacks-js-sending-transactions) + +## Complete Apps + +[Sup](https://github.com/kenrogers/sup) + +[Hello Stacks](https://github.com/kenrogers/hello-stacks) From 14c7ea8f2bd6fe708a3cf13c1b498c095421875d Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:44:22 +0100 Subject: [PATCH 0460/1444] New translations btc-connection.md (Turkish) --- .../current/stacks-academy/btc-connection.md | 196 ++++++++++++++++++ 1 file changed, 196 insertions(+) create mode 100644 i18n/tr/docusaurus-plugin-content-docs/current/stacks-academy/btc-connection.md diff --git a/i18n/tr/docusaurus-plugin-content-docs/current/stacks-academy/btc-connection.md b/i18n/tr/docusaurus-plugin-content-docs/current/stacks-academy/btc-connection.md new file mode 100644 index 0000000000..b4db915969 --- /dev/null +++ b/i18n/tr/docusaurus-plugin-content-docs/current/stacks-academy/btc-connection.md @@ -0,0 +1,196 @@ +--- +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. + +## Stacks Among Other Bitcoin Layers + +In the [last section](./what-is-stacks.md) we covered what Stacks actually is and what problem it is solving, but this is not a new problem. The Bitcoin write problem has been a bit of a holy grail problem in the crypto world for a while now. + +Bitcoin is the OG cryptocurrency and has the largest market cap, but it also some of the least functionality, which means if we want to make it a productive asset and use it to build a decentralized economy, we need to take a layered approach and let Bitcoin do what it does best, while creating additional layers on top of it to add functionality. + +So how does Stacks compare to some of the other approaches to layering on top of Bitcoin? + +### 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. + +## 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. + +But because it has its own execution environment and smart contract state to maintain, it needs a token to incentivize maintenance of the network. + +But it goes further than that. It is possible to build a system like this without a token using something like merge-mining or a sidechain, but then we lose out on the additional benefit of having the chain state's safety underpinned by its entire token economy's value. + +In the case of Stacks, the safety and liveness of the chain are underpinned by this value, and the stacking mechanism incentivizes network members to increase this value. + +From Jude Nelson, Stacks core developer: + +"How hard is it to cause a safety failure (i.e. a double-spend via a reorg) on just the canonical Stacks chain fork? Anyone can become a miner by spending BTC, so without loss of generality, reverting the last block on the canonical chain is at least as hard in expectation as spending more BTC than the rest of the miners combined for that block. Because each Bitcoin block selects at most one Stacks block, the act of reorging the canonical Stacks chain back N blocks is the act of winning at least N + 1 blocks built off of a common ancestor that is N blocks deep. This is a lower bound on the number of Bitcoin blocks mined during which a reorg needs to take place — in practice, honest miners will keep working on the canonical chain, and will win some Stacks blocks of their own, which in turn increases the number of Stacks blocks the reorging miners must win. + +How costly is it to carry out a reorg of N blocks? It’s a function of how valuable STX is relative to BTC — the more valuable STX are, the more BTC honest miners are committing to mining (this has borne out in practice), and thus the more BTC a reorging miner must commit. Therefore, the cost of a reorg is a function of the value of STX. + +This is similar to the economic security of a PoW blockchain. Like in PoW, each fork of the Stacks chain has its own independent “security budget” — an attacker must out-spend the security budget to carry out a reorg, and the security budget is a function of the block rewards. In PoX, the only difference is that the miners spend another blockchain’s tokens (BTC in Stacks’ case) instead of energy. Therefore, Stacks can’t be a sidechain, a drivechain, or a merge-mined chain, because none of these other systems’ security budgets are a function of their tokens’ worth. Sidechains, drivechains, and merged-mined chains all rely on external miners for their safety, since their safety is guaranteed in part by external miners validating their blocks. The onus on these systems is to get external miners to care enough to do so, and in the case of sidechains, drivechains, and blind merged-mined chains, there is an additional onus to encourage their nodes to mine blocks at all (since there is no on-chain reward for them to earn by doing so). By contrast, disinterested Bitcoin miners neither assist nor prevent a reorg in PoX — they only record the history of all Stacks forks. + +PoX offers two additional, unique security properties on top of PoW. First, no matter how much BTC a reorging miner can commit, the act of executing a reorg is going to be time-consuming. Unless the attacker can attack the Bitcoin chain itself by quickly producing a better Bitcoin fork, a reorging miner must sustain the attack for at least N + 1 Bitcoin blocks. This gives honest miners and users ample time to notice and react to the reorg attempt. + +Second, the history of block production in all Stacks forks is embedded within Bitcoin. This allows the system to leverage Bitcoin’s security budget in order to ensure that all forks are public. This is because the act of producing a hidden Stacks fork, where the fork’s block hashes are not known to the honest miners, is the act of producing a hidden canonical Bitcoin fork. Therefore, the act of producing a hidden Stacks fork is at least as hard as reorging the Bitcoin chain. A PoX chain leverages this property not to prevent reorgs, but to make reorgs unprofitable. + +By anchoring blocks to an existing blockchain, a PoX chain forces reorgs to happen out in the open, thereby giving advance warning to all honest network participants when they happen. Honest miners, users, and exchanges will see the PoX transactions for reorg attempts on the existing blockchain, and adapt their behaviors accordingly: honest miners will increase their commitments, and users and exchanges will require more confirmations for transactions. This makes the act of carrying out a reorg while also making a profit much more challenging, since malicious reorgs — like selfish mining and double-spending — rely on secrecy to work effectively. Specific to Stacks, miners are additionally required to mine for a “warm-up” period of two blocks, during which they must spend BTC at their target commit levels but will not win any Stacks blocks. So, a high-budget reorg attempt will not only be costly, but will also alert the rest of the network before the damage is done." + +- [What Kind of Blockchain is Stacks?](https://stacks.org/stacks-blockchain) + +## 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) From b5cd70f1b8c364e08b08566c94ad1d25b85bf28b Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:44:23 +0100 Subject: [PATCH 0461/1444] New translations post-conditions.md (Turkish) --- .../current/stacks-academy/post-conditions.md | 39 +++++++++++++++++++ 1 file changed, 39 insertions(+) create mode 100644 i18n/tr/docusaurus-plugin-content-docs/current/stacks-academy/post-conditions.md diff --git a/i18n/tr/docusaurus-plugin-content-docs/current/stacks-academy/post-conditions.md b/i18n/tr/docusaurus-plugin-content-docs/current/stacks-academy/post-conditions.md new file mode 100644 index 0000000000..bb0727194f --- /dev/null +++ b/i18n/tr/docusaurus-plugin-content-docs/current/stacks-academy/post-conditions.md @@ -0,0 +1,39 @@ +--- +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). From cd771c1343498f7f0b2078ac032fcb2f9b05b875 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:44:24 +0100 Subject: [PATCH 0462/1444] New translations creating-an-ft.md (Turkish) --- .../current/cookbook/creating-an-ft.md | 99 +++++++++++++++++++ 1 file changed, 99 insertions(+) create mode 100644 i18n/tr/docusaurus-plugin-content-docs/current/cookbook/creating-an-ft.md diff --git a/i18n/tr/docusaurus-plugin-content-docs/current/cookbook/creating-an-ft.md b/i18n/tr/docusaurus-plugin-content-docs/current/cookbook/creating-an-ft.md new file mode 100644 index 0000000000..4e3bad99d2 --- /dev/null +++ b/i18n/tr/docusaurus-plugin-content-docs/current/cookbook/creating-an-ft.md @@ -0,0 +1,99 @@ +--- +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) + ) +) +``` From 3337b00ed7a36e64daa530780ce33568751e6257 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:44:24 +0100 Subject: [PATCH 0463/1444] New translations creating-an-nft.md (Turkish) --- .../current/cookbook/creating-an-nft.md | 87 +++++++++++++++++++ 1 file changed, 87 insertions(+) create mode 100644 i18n/tr/docusaurus-plugin-content-docs/current/cookbook/creating-an-nft.md diff --git a/i18n/tr/docusaurus-plugin-content-docs/current/cookbook/creating-an-nft.md b/i18n/tr/docusaurus-plugin-content-docs/current/cookbook/creating-an-nft.md new file mode 100644 index 0000000000..08faf9393a --- /dev/null +++ b/i18n/tr/docusaurus-plugin-content-docs/current/cookbook/creating-an-nft.md @@ -0,0 +1,87 @@ +--- +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 +Code for this recipe has been pulled from [this NFT tutorial](https://blog.developerdao.com/building-an-nft-with-stacks-and-clarity) from Developer DAO. +::: + +## 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) + ) +) +``` From 66219cb191243c66cea4c5250c155afcd7523a21 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:44:25 +0100 Subject: [PATCH 0464/1444] New translations post-conditions.md (Turkish) --- .../current/cookbook/post-conditions.md | 136 ++++++++++++++++++ 1 file changed, 136 insertions(+) create mode 100644 i18n/tr/docusaurus-plugin-content-docs/current/cookbook/post-conditions.md diff --git a/i18n/tr/docusaurus-plugin-content-docs/current/cookbook/post-conditions.md b/i18n/tr/docusaurus-plugin-content-docs/current/cookbook/post-conditions.md new file mode 100644 index 0000000000..571fc20d48 --- /dev/null +++ b/i18n/tr/docusaurus-plugin-content-docs/current/cookbook/post-conditions.md @@ -0,0 +1,136 @@ +--- +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. From 91567c70a1aee182329e376f5bea9eba74247525 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:44:26 +0100 Subject: [PATCH 0465/1444] New translations stacks-js-auth.md (Turkish) --- .../current/cookbook/stacks-js-auth.md | 98 +++++++++++++++++++ 1 file changed, 98 insertions(+) create mode 100644 i18n/tr/docusaurus-plugin-content-docs/current/cookbook/stacks-js-auth.md diff --git a/i18n/tr/docusaurus-plugin-content-docs/current/cookbook/stacks-js-auth.md b/i18n/tr/docusaurus-plugin-content-docs/current/cookbook/stacks-js-auth.md new file mode 100644 index 0000000000..89d1f06e00 --- /dev/null +++ b/i18n/tr/docusaurus-plugin-content-docs/current/cookbook/stacks-js-auth.md @@ -0,0 +1,98 @@ +--- +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 && ( + + ); +} +``` From 634692beefb9d04fb5f9312d6bd6c751acd467ff Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:44:27 +0100 Subject: [PATCH 0466/1444] New translations stacks-js-sending-transactions.md (Turkish) --- .../stacks-js-sending-transactions.md | 55 +++++++++++++++++++ 1 file changed, 55 insertions(+) create mode 100644 i18n/tr/docusaurus-plugin-content-docs/current/cookbook/stacks-js-sending-transactions.md diff --git a/i18n/tr/docusaurus-plugin-content-docs/current/cookbook/stacks-js-sending-transactions.md b/i18n/tr/docusaurus-plugin-content-docs/current/cookbook/stacks-js-sending-transactions.md new file mode 100644 index 0000000000..849c7d1f42 --- /dev/null +++ b/i18n/tr/docusaurus-plugin-content-docs/current/cookbook/stacks-js-sending-transactions.md @@ -0,0 +1,55 @@ +--- +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. From 2ddd4a55db125dd17d0f066701ca588b880c404c Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:44:28 +0100 Subject: [PATCH 0467/1444] New translations _category_.json (Turkish) --- .../current/clarity/noteworthy-contracts/_category_.json | 8 ++++++++ 1 file changed, 8 insertions(+) create mode 100644 i18n/tr/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/_category_.json diff --git a/i18n/tr/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/_category_.json b/i18n/tr/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/_category_.json new file mode 100644 index 0000000000..f5de305558 --- /dev/null +++ b/i18n/tr/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/_category_.json @@ -0,0 +1,8 @@ +{ + "label": "Noteworthy Contracts", + "position": 4, + "link": { + "type": "generated-index", + "description": "Specific deployed Clarity Contracts worth mentioning." + } +} \ No newline at end of file From 5880a4e69576608430f47ecad0855344c501f2d5 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:44:29 +0100 Subject: [PATCH 0468/1444] New translations bns-contract.md (Turkish) --- .../noteworthy-contracts/bns-contract.md | 519 ++++++++++++++++++ 1 file changed, 519 insertions(+) create mode 100644 i18n/tr/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/bns-contract.md diff --git a/i18n/tr/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/bns-contract.md b/i18n/tr/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/bns-contract.md new file mode 100644 index 0000000000..a7770b7d24 --- /dev/null +++ b/i18n/tr/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/bns-contract.md @@ -0,0 +1,519 @@ +--- +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 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` From 4a66a97a29b6673199e4eecccb2ff3baa2163fb9 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:44:30 +0100 Subject: [PATCH 0469/1444] New translations xbtc.md (Turkish) --- .../clarity/noteworthy-contracts/xbtc.md | 28 +++++++++++++++++++ 1 file changed, 28 insertions(+) create mode 100644 i18n/tr/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/xbtc.md diff --git a/i18n/tr/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/xbtc.md b/i18n/tr/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/xbtc.md new file mode 100644 index 0000000000..e535dcf260 --- /dev/null +++ b/i18n/tr/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/xbtc.md @@ -0,0 +1,28 @@ +--- +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) From 0122eb9c1e0f8bae4443076511374c553b3c408b Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:44:30 +0100 Subject: [PATCH 0470/1444] New translations index.md (Turkish) --- .../current/glossary/index.md | 284 ++++++++++++++++++ 1 file changed, 284 insertions(+) create mode 100644 i18n/tr/docusaurus-plugin-content-docs/current/glossary/index.md diff --git a/i18n/tr/docusaurus-plugin-content-docs/current/glossary/index.md b/i18n/tr/docusaurus-plugin-content-docs/current/glossary/index.md new file mode 100644 index 0000000000..419c0e0d73 --- /dev/null +++ b/i18n/tr/docusaurus-plugin-content-docs/current/glossary/index.md @@ -0,0 +1,284 @@ +--- +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. From c1e1c4fab20e69b1dc77e4e21803aa10671b3ca2 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:44:31 +0100 Subject: [PATCH 0471/1444] New translations quicknode.md (Turkish) --- .../current/nodes-and-miners/quicknode.md | 45 +++++++++++++++++++ 1 file changed, 45 insertions(+) create mode 100644 i18n/tr/docusaurus-plugin-content-docs/current/nodes-and-miners/quicknode.md diff --git a/i18n/tr/docusaurus-plugin-content-docs/current/nodes-and-miners/quicknode.md b/i18n/tr/docusaurus-plugin-content-docs/current/nodes-and-miners/quicknode.md new file mode 100644 index 0000000000..1281964689 --- /dev/null +++ b/i18n/tr/docusaurus-plugin-content-docs/current/nodes-and-miners/quicknode.md @@ -0,0 +1,45 @@ +--- +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. From 4b095c7cb869446c935249b1133bc5db218b0f37 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:44:32 +0100 Subject: [PATCH 0472/1444] New translations defi.md (Turkish) --- .../current/services-using-stacks/defi.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) 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 index 51defacba7..58717a3234 100644 --- 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 @@ -26,7 +26,7 @@ Please edit this page to add any relevant new site that we are missing. ## Lnswap -[LNSWAP](https://www.lnswap.org). Non custiodial crypto currency exchange +[LNSWAP](https://www.lnswap.org). Non-custodial crypto currency exchange ![](/img/sh_lnswap.png) @@ -41,4 +41,3 @@ Please edit this page to add any relevant new site that we are missing. [Stackswap](https://app.stackswap.org/v2) ![](/img/sh_stackswap.png) - From 5a5b9ec32ba5aad05d585b5d850e129953dd135f Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:44:33 +0100 Subject: [PATCH 0473/1444] New translations more.md (Turkish) --- .../current/services-using-stacks/more.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) 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 index df0b3e2254..1e14b9a5a5 100644 --- 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 @@ -18,6 +18,6 @@ Please edit this page to add any relevant new site that we are missing. ## Sigle -[Sigle](https://www.sigle.io/) is a decentralised and open source web 3 writing platform. +[Sigle](https://www.sigle.io/) is a decentralized and open source web 3 writing platform. -![](/img/sh_sigle.png) \ No newline at end of file +![](/img/sh_sigle.png) From 76a872a2b8011a5bdf37b8a6b208d76a5624501d Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:44:34 +0100 Subject: [PATCH 0474/1444] New translations nft.md (Turkish) --- .../current/services-using-stacks/nft.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) 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 index abb770663c..d582604854 100644 --- 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 @@ -15,6 +15,7 @@ Please edit this page to add any relevant new site that we are missing. ![website-screenshot](/img/sh_nft_byzantion.png) ### [Gamma](https://gamma.io/) + ![website-screenshot](/img/sh_nft_gamma.png) ### [Megapont](https://www.megapont.com/) @@ -35,4 +36,4 @@ Please edit this page to add any relevant new site that we are missing. ### [Superfandom](https://superfandom.io/) -![website-screenshot](/img/sh_superfandom.png) \ No newline at end of file +![website-screenshot](/img/sh_superfandom.png) From 4b27e5db5512e1c3967190bfbeaf40695525b8b7 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:44:35 +0100 Subject: [PATCH 0475/1444] New translations stacks-info-sites.md (Turkish) --- .../current/services-using-stacks/stacks-info-sites.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) 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 index 35ced8dac6..54f6823e33 100644 --- 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 @@ -30,7 +30,7 @@ Please edit this page to add any relevant new site that we are missing. ![website-screenshot](/img/sh_stxstats.png) -### [Novuminsights](https://stacks.novuminsights.com/health) +### [Novum Insights](https://stacks.novuminsights.com/health) ![website-screenshot](/img/sh_novuminsights.png) From 9eaa242a4fef2161e7a5823f8d17b964db72ac08 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:44:36 +0100 Subject: [PATCH 0476/1444] New translations wallets.md (Turkish) --- .../current/services-using-stacks/wallets.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) 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 index e5ea6c5b45..2d3fcc85f2 100644 --- 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 @@ -15,6 +15,7 @@ Please edit this page to add any relevant new site that we are missing. [Blockchain.com](https://www.blockchain.com/wallet) ![](/img/sh_blockchain.png) + ## Boom [Boom](https://boom.money) @@ -26,6 +27,7 @@ Please edit this page to add any relevant new site that we are missing. [D'CENT](https://dcentwallet.com) ![](/img/sh_dcent.png) + ## Hiro Wallet [Hiro Wallet](https://www.hiro.so/wallet) @@ -48,4 +50,4 @@ Please edit this page to add any relevant new site that we are missing. [Wise](https://wiseapp.id) -![](/img/sh_wiseapp.png) \ No newline at end of file +![](/img/sh_wiseapp.png) From 6570eb493a219c5cc4877112f95dece1a7eefa3e Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:44:36 +0100 Subject: [PATCH 0477/1444] New translations whitepapers.md (Turkish) --- .../current/stacks-academy/whitepapers.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) create mode 100644 i18n/tr/docusaurus-plugin-content-docs/current/stacks-academy/whitepapers.md diff --git a/i18n/tr/docusaurus-plugin-content-docs/current/stacks-academy/whitepapers.md b/i18n/tr/docusaurus-plugin-content-docs/current/stacks-academy/whitepapers.md new file mode 100644 index 0000000000..0e564fbf44 --- /dev/null +++ b/i18n/tr/docusaurus-plugin-content-docs/current/stacks-academy/whitepapers.md @@ -0,0 +1,12 @@ +--- +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) From 254f6c717e0c9a71019348f6f059859ca88c667e Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:44:37 +0100 Subject: [PATCH 0478/1444] New translations stacking-contract.md (Turkish) --- .../noteworthy-contracts/stacking-contract.md | 352 ++++++++++++++++++ 1 file changed, 352 insertions(+) create mode 100644 i18n/tr/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/stacking-contract.md diff --git a/i18n/tr/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/stacking-contract.md b/i18n/tr/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/stacking-contract.md new file mode 100644 index 0000000000..c0027256cd --- /dev/null +++ b/i18n/tr/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/stacking-contract.md @@ -0,0 +1,352 @@ +--- +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. 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` From 6eb56ca5d10b7be830ebd9e6f2d36129c680833b Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:44:38 +0100 Subject: [PATCH 0479/1444] New translations index.md (Turkish) --- .../current/next-steps/index.md | 39 +++++++++++++++++++ 1 file changed, 39 insertions(+) create mode 100644 i18n/tr/docusaurus-plugin-content-docs/current/next-steps/index.md diff --git a/i18n/tr/docusaurus-plugin-content-docs/current/next-steps/index.md b/i18n/tr/docusaurus-plugin-content-docs/current/next-steps/index.md new file mode 100644 index 0000000000..00ddec9178 --- /dev/null +++ b/i18n/tr/docusaurus-plugin-content-docs/current/next-steps/index.md @@ -0,0 +1,39 @@ +--- +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) From 2a8a55a153b73ca791604aba0626ff0000fd6520 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:44:39 +0100 Subject: [PATCH 0480/1444] New translations sips.md (Turkish) --- .../current/stacks-academy/sips.md | 52 +++++++++++++++++++ 1 file changed, 52 insertions(+) create mode 100644 i18n/tr/docusaurus-plugin-content-docs/current/stacks-academy/sips.md diff --git a/i18n/tr/docusaurus-plugin-content-docs/current/stacks-academy/sips.md b/i18n/tr/docusaurus-plugin-content-docs/current/stacks-academy/sips.md new file mode 100644 index 0000000000..aa2db18e62 --- /dev/null +++ b/i18n/tr/docusaurus-plugin-content-docs/current/stacks-academy/sips.md @@ -0,0 +1,52 @@ +--- +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/IJ15791776) 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-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. From ff5d1783193f9b52197b22fb812e0f0ad2511c9d Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:44:40 +0100 Subject: [PATCH 0481/1444] New translations hosted-nodes.md (Turkish) --- .../current/nodes-and-miners/hosted-nodes.md | 25 +++++++++++++++++++ 1 file changed, 25 insertions(+) create mode 100644 i18n/tr/docusaurus-plugin-content-docs/current/nodes-and-miners/hosted-nodes.md diff --git a/i18n/tr/docusaurus-plugin-content-docs/current/nodes-and-miners/hosted-nodes.md b/i18n/tr/docusaurus-plugin-content-docs/current/nodes-and-miners/hosted-nodes.md new file mode 100644 index 0000000000..12d86c7ee2 --- /dev/null +++ b/i18n/tr/docusaurus-plugin-content-docs/current/nodes-and-miners/hosted-nodes.md @@ -0,0 +1,25 @@ +--- +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. From dffa46e64196b27d0e26889e4aa6f685c0364287 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:44:40 +0100 Subject: [PATCH 0482/1444] New translations authentication.md (Chinese Simplified) --- .../current/stacks-academy/authentication.md | 63 +++++++++++++++++++ 1 file changed, 63 insertions(+) create mode 100644 i18n/zh/docusaurus-plugin-content-docs/current/stacks-academy/authentication.md diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/stacks-academy/authentication.md b/i18n/zh/docusaurus-plugin-content-docs/current/stacks-academy/authentication.md new file mode 100644 index 0000000000..4dba632620 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/current/stacks-academy/authentication.md @@ -0,0 +1,63 @@ +--- +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. 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. From bb97b6b1a9cf2c26d105fe0270a31c808d430f35 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:44:41 +0100 Subject: [PATCH 0483/1444] New translations bns.md (Chinese Simplified) --- .../current/stacks-academy/bns.md | 276 ++++++++++++++++++ 1 file changed, 276 insertions(+) create mode 100644 i18n/zh/docusaurus-plugin-content-docs/current/stacks-academy/bns.md diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/stacks-academy/bns.md b/i18n/zh/docusaurus-plugin-content-docs/current/stacks-academy/bns.md new file mode 100644 index 0000000000..e09390aefe --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/current/stacks-academy/bns.md @@ -0,0 +1,276 @@ +--- +title: Blockchain Naming System +description: Binds Stacks usernames to off-chain state +sidebar_position: 8 +--- + +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 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. 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). From 433d296138d48c61ceb655ec7383090735f42de0 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:44:42 +0100 Subject: [PATCH 0484/1444] New translations docs.md (Chinese Simplified) --- .../current/contribute/docs.md | 24 ++++++++++++------- 1 file changed, 15 insertions(+), 9 deletions(-) diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/contribute/docs.md b/i18n/zh/docusaurus-plugin-content-docs/current/contribute/docs.md index 38c3e19d43..4732eb19e9 100644 --- a/i18n/zh/docusaurus-plugin-content-docs/current/contribute/docs.md +++ b/i18n/zh/docusaurus-plugin-content-docs/current/contribute/docs.md @@ -7,7 +7,7 @@ description: Learn how this site is built, and how you can contribute to it. 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). +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? :::tip Don't know what Markdown is? Want to learn? Here is a [helpful guide](https://guides.github.com/features/mastering-markdown/). @@ -15,7 +15,7 @@ Don't want to learn it? No need to. Don't want to learn it? No need to. Write [i :::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 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). @@ -24,28 +24,32 @@ To add new content, they are two different ways to do it, the [easy way](#easy-w [**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. +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. `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. + - `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. -## Aditional information +## 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. This is enough to preview your changes. + ```bash npx docusaurus start ``` @@ -54,8 +58,8 @@ Before running this command for the first time you will need to run `npm install 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 ``` @@ -91,7 +95,7 @@ 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. +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 @@ -124,6 +128,7 @@ And execute prettier with the following command: npx prettier --write mynewfiletocheck.md ``` --> + ### 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. @@ -138,6 +143,7 @@ To write a code block, you need to wrap your code in ` ```language `, and end yo (define-public (get-counter) (ok (var-get counter))) ``` + ### Admonitions You can use the following admonitions to highlight content. @@ -234,4 +240,4 @@ Some **content** with _markdown_ `syntax`. Check [this `api`](#). Some **content** with _markdown_ `syntax`. Check [this `api`](#). -::: \ No newline at end of file +::: From c716caa5dfa42bfa4ed5312304fb490fdfe6d94f Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:44:44 +0100 Subject: [PATCH 0485/1444] New translations translations.md (Chinese Simplified) --- .../current/contribute/translations.md | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/contribute/translations.md b/i18n/zh/docusaurus-plugin-content-docs/current/contribute/translations.md index fa419be8be..37b1fb40c9 100644 --- a/i18n/zh/docusaurus-plugin-content-docs/current/contribute/translations.md +++ b/i18n/zh/docusaurus-plugin-content-docs/current/contribute/translations.md @@ -1,12 +1,11 @@ --- title: Contribute with translations -description: Want to help tranlating these docs to your local language? +description: Want to help translating 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. +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. @@ -14,13 +13,13 @@ 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. +::: 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 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. +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`). 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) From fa3097c1bb7682e87a16109ab2e89cca7ce39179 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:44:46 +0100 Subject: [PATCH 0486/1444] New translations gaia-on-ec2.md (Chinese Simplified) --- .../current/gaia/gaia-on-ec2.md | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) 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 index 2dd4b2ca9a..16376c17ee 100644 --- 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 @@ -26,9 +26,10 @@ Use a link in the table to launch the [CloudFormation](https://console.aws.amazo ### Step 2 - Setup stack using template -You need to configure the template with the appropiate values for your hub and domain it runs on. +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 ``` @@ -52,7 +53,7 @@ Specify the stack details and then click `Next`: ![Specify template](/img/cloudf | 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`. | +| InstanceType | 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 | @@ -93,7 +94,9 @@ ssh -i admin@ 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 +![](/img/cloudformation-gaia-template1-designer.png) From 6d47c0f6a82e35cd829aef6fbd35b45c0b07bd27 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:44:47 +0100 Subject: [PATCH 0487/1444] New translations gaia.md (Chinese Simplified) --- .../current/gaia/gaia.md | 12 +++++++++--- 1 file changed, 9 insertions(+), 3 deletions(-) diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/gaia/gaia.md b/i18n/zh/docusaurus-plugin-content-docs/current/gaia/gaia.md index 5718b504f2..05d446cccd 100644 --- a/i18n/zh/docusaurus-plugin-content-docs/current/gaia/gaia.md +++ b/i18n/zh/docusaurus-plugin-content-docs/current/gaia/gaia.md @@ -1,14 +1,20 @@ --- title: Gaia description: Decentralized storage architecture for off-chain data -sidebar_position: 5 +sidebar_position: 6 tags: - gaia --- ## Introduction -Apps built with the Stacks blockchain store off-chain data using a storage system called Gaia. +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. @@ -38,7 +44,7 @@ The Stacks blockchain stores only identity data. Data created by the actions of 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) +![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. 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. From 90c6156f4d4ca36590006c7cf48189cef51e0c5e Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:44:48 +0100 Subject: [PATCH 0488/1444] New translations setup-linux.md (Chinese Simplified) --- .../current/gaia/setup-linux.md | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) 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 index dea034dd65..0d4b1db45d 100644 --- a/i18n/zh/docusaurus-plugin-content-docs/current/gaia/setup-linux.md +++ b/i18n/zh/docusaurus-plugin-content-docs/current/gaia/setup-linux.md @@ -1,6 +1,6 @@ --- 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. +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 background. tags: - tutorial - gaia @@ -19,8 +19,7 @@ This configuration will setup the following 4 docker containers: 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:

+**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 @@ -48,8 +47,7 @@ chmod +x ${DESTINATION_DC}/docker-compose 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.

+**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 From 0e73e457be66e94cce122212ff4f6004910e9263 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:44:50 +0100 Subject: [PATCH 0489/1444] New translations digitalocean.md (Chinese Simplified) --- .../current/nodes-and-miners/digitalocean.md | 41 +++++++++++-------- 1 file changed, 25 insertions(+), 16 deletions(-) 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 index 99aeac842b..9f84425f21 100644 --- 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 @@ -1,28 +1,30 @@ --- -title: 数码海洋上的应用 +title: Run a Node with Digital Ocean description: A guide to setup Stacks on DigitalOcean -sidebar_position: 4 +sidebar_position: 2 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). +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`. Click on `Create Stacks Blockchain Droplet`. Click on `Create Stacks Blockchain Droplet`. +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`. ![](/img/sh_digitalocean-marketplace.png) #### 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) +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 if your prefer. +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) @@ -46,41 +48,48 @@ Congratulations! Congratulations! You are now running the Stacks Blockchain. Con ## 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). +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`. -Once the stacks blockchain starts to sync with peers, application ports will open and nginx port 80 will now start proxying requests. +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 v3.0.3 (master:cd0c8aef)", + "server_version": "stacks-blockchain-api v6.2.3 (master:77ab3ae2)", "status": "ready", "chain_tip": { - "block_height": 16220, - "block_hash": "0x3123fba9c0de6b569573494cf83c1d5d198a66bfd5f48ef97949b6bf11ba13be", - "index_block_hash": "0xeec960fbbd6186b4ccac85ce12adba72be497d881f81e077305c90955b51a6ae" + "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/README.md#quickstart). +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). -## API Creation +## 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. 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. +:::note _The `name`, `region` and `size` values below are hardcoded, so adjust as desired._ ::: + ```bash -curl -X POST -H 'Content-Type: application/json' \ +$ export TOKEN= +$ 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"}' \ + '{"name":"stacks-blockchain","region":"sfo2","size":"s-2vcpu-4gb","image":"stacksfoundation-stacksblockchain"}' \ "https://api.digitalocean.com/v2/droplets" ``` From 4105d5a1fd244d4bf43f52c0a32268fa34bf9692 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:44:50 +0100 Subject: [PATCH 0490/1444] New translations index.md (Chinese Simplified) --- .../current/nodes-and-miners/index.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) 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 index b6cbb9754a..e5f4f2c250 100644 --- 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 @@ -1,11 +1,11 @@ --- title: Nodes and Miners description: Nodes and Miners -sidebar_position: 7 +sidebar_position: 5 --- -Here are all the steps to run nodes and miners, both on mainnet and testnet. +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. -## What's a Stacks node? +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. -## What's a Stacks miner? +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. From 2593114903216b1259987ec6160a181b8f08b1f7 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:44:51 +0100 Subject: [PATCH 0491/1444] New translations miner-mainnet.md (Chinese Simplified) --- .../current/nodes-and-miners/miner-mainnet.md | 394 +++++------------- 1 file changed, 111 insertions(+), 283 deletions(-) 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 index 751a5f87b7..67ee36c015 100644 --- 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 @@ -1,197 +1,100 @@ --- title: Mine mainnet Stacks tokens -description: Set up and run a miner on the Stacks 2.0 mainnet -sidebar_position: 5 +description: Set up and run a miner on Stacks Mainnet +sidebar_position: 6 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. +For more on the technical details of mining, please review the [mining guide](../stacks-academy/mining) -If you're interested in mining on the testnet, you can find instructions on how to do that [here](miner-testnet): +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 want to learn more about the technical details of mining, please review the [mining guide](../understand-stacks/mining): +If you're interested in mining on the Stacks testnet, you can find instructions on how to do that [here](miner-testnet): -## Running bitcoind locally +## Running a Bitcoin Mainnet Full Node -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) +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. -First, download the bitcoind software for your platform from https://bitcoin.org/en/download. +- [Ensure your computer meets the minimum hardware requirements before continuing.](https://bitcoin.org/en/bitcoin-core/features/requirements#system-requirements) -Next, start bitcoind with the following configuration: +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): -```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 - } -} -``` +:::tip It is recommened to use a persistent location for the chainstate, in the steps below we're using `/bitcoin` ::: -**Don't lose this information** - we'll need to use the `privateKey` field later on. +### Update the Bitcoin Configuration File -The above BTC address will then need to be imported into the BTC network. +Next, update the bitcoin configuration: -```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: +- **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 -[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 = "" -... +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 ``` -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. +### Start Bitcoin -To run your miner, run this in the command line: +Finally, start bitcoin as follows (adjust the `conf` path to where it was created in the previous step, i.e. `$HOME/bitcoin.conf`): ```bash -stacks-node start --config=./testnet/stacks-node/conf/mainnet-miner-conf.toml +bitcoind -conf=$HOME/bitcoin.conf ``` -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 -``` +:::note +It will take a few days for the node to synchronize with Bitcoin mainnet. +::: -The above code will compile an optimized binary. To use it, run: To use it, run: To use it, run: +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 -cd ../.. -cd ../.. -cd ../.. -./target/release/stacks-node start --config=./mainnet-miner-conf.toml +$ bitcoin-cli \ + -rpcconnect=localhost \ + -rpcport=8332 \ + -rpcuser=btcuser \ + -rpcpassword=btcpassword \ +getblockchaininfo | jq .blocks +773281 ``` -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 +## Running a Stacks Blockchain miner -### Prerequisites +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) -Make sure are [running a node](run-a-node) and [running bitcoind locally](#running-bitcoind-locally) before starting this tutorial. +_There may be some extra requirements to building, [defined here](https://github.com/stacksfoundation/miner-docs/blob/main/prerequisites.md#install-required-packages)_ -### Generate keychain and get mainnet tokens in Windows +:::tip It is recommened to use a persistent location for the chainstate, in the steps below we're using `/stacks-blockchain` ::: -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. +### Generate a keychain -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. +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. With this keychain, we'll purchase some BTC from a cryptocurrency exchange, and then use that BTC to start mining. -Generate a keychain: +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 -npm install --global @stacks/cli -stx make_keychain > cli_keychain.json -type cli_keychain.json +npx @stacks/cli make_keychain 2>/dev/null | jq -r ``` -After this runs, you'll probably see some installation logs, and at the end you should see some JSON that looks like this: +After this runs, you should see some JSON printed to the screen that looks like this: ```json { @@ -205,169 +108,99 @@ After this runs, you'll probably see some installation logs, and at the end you } ``` -:::tip Check out the [Stacks CLI reference](https://docs.hiro.so/references/stacks-cli) for more details ::: +:::warning **Do not lose this information** - we'll need to use the `privateKey` and `btcAddress` fields in later steps. ::: -The above BTC address will then need to be imported into the BTC network. +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=your-user -rpcpassword=your-password importaddress +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). 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). 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 Stacks Blockchain Configuration File -Update the following properties: +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`. -```toml -[node] -... -[node] -... -# Enter your private key here -seed = "replace-with-your-private-key" -local_peer_seed = "replace-with-your-private-key" -... +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. -[burnchain] -... -[node] -... -# Enter your private key here -seed = "replace-with-your-private-key" -local_peer_seed = "replace-with-your-private-key" -... +Next, update the bitcoin configuration: -[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 = "" -... +- **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`) -[burnchain] -... +```toml [node] -... -# Enter your private key here -seed = "replace-with-your-private-key" -local_peer_seed = "replace-with-your-private-key" -... +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] -... -# To mine on mainnet, you need to run bitcoind locally -# Details can be found in above section, 'Running bitcoind locally' +chain = "bitcoin" +mode = "mainnet" peer_host = "127.0.0.1" -username = "" -password = "" -... +username = "" +password = "" +rpc_port = 8332 +peer_port = 8333 +satoshis_per_byte = 100 +burn_fee_cap = 20000 ``` -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. +### Start the Stacks Blockchain -### Run the miner - -To start your miner, run this in the command line: +To run your miner, run this in the command line: ```bash -stacks-node start --config=testnet/stacks-node/conf/mainnet-miner-conf.toml +stacks-node start --config=$HOME/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. +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. -### Enable debug logging in Windows +### 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 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 -set RUST_BACKTRACE=full; -set STACKS_LOG_DEBUG=1; -stacks-node start --config=mainnet-miner-conf.toml +STACKS_LOG_DEBUG=1 stacks-node start --config=$HOME/mainnet-miner-conf.toml ``` -## Optional: Running with Docker +--- + +## Optional: Running a Stacks Blockchain miner with Docker -Alternatively, you can run the mainnet node with Docker. +Alternatively, you can run a Stacks mainnet miner with Docker. -:::caution Ensure you have [Docker](https://docs.docker.com/get-docker/) installed on your machine. ::: ::: ::: +:::caution Ensure you have [Docker](https://docs.docker.com/get-docker/) installed. ::: -### Generate keychain and get tokens +### 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 +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. 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 +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). 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). -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 Stacks Blockchain Docker Configuration File -Update the following properties: +Use the steps oulined above to create the [configuration file](miner-mainnet#update-the-stacks-blockchain-configuration-file) -```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 +### 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 ::: If removed, debug logs will be disabled ::: If removed, debug logs will be disabled ::: @@ -378,7 +211,8 @@ docker run -d \ --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" \ + -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 \ @@ -393,9 +227,9 @@ 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). +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 on your machine: +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) @@ -404,13 +238,7 @@ Ensure you have the following prerequisites installed on your machine: ### 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). +Use the steps [outlined above](miner-mainnet#generate-a-keychain-and-get-some-tokens) ### Install the chart and run the miner From 9d75e0d2c4f15e0516db3b92e860baf140978bb3 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:44:52 +0100 Subject: [PATCH 0492/1444] New translations miner-testnet.md (Chinese Simplified) --- .../current/nodes-and-miners/miner-testnet.md | 398 ++++++------------ 1 file changed, 128 insertions(+), 270 deletions(-) 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 index 7dc2ac76ca..c655e31ba3 100644 --- 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 @@ -1,35 +1,52 @@ --- title: Mine testnet Stacks tokens -description: Set up and run a miner on the Stacks 2.0 testnet -sidebar_position: 4 +description: Set up and run a miner on Stacks Testnet +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 testnet. +For more on the technical details of mining, please review the [mining guide](../stacks-academy/mining) -If you want to learn more about the technical details of mining, please review the [mining guide](../understand-stacks/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)). -## Running bitcoind locally +If you're interested in mining on the Stacks mainnet, you can find instructions on how to do that [here](miner-mainnet): -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) +## Running a Bitcoin Testnet Full Node -First, download the bitcoind software for your platform from https://bitcoin.org/en/download. +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. -Next, start bitcoind with the following configuration: +- [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 -rpcuser=your-bitcoind-username -rpcpassword=your-bitcoind-password testnet=1 -txindex=0 -listen=1 -rpcserialversion=0 -maxorphantx=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 @@ -37,155 +54,51 @@ 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. +### Start Bitcoin -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: +Finally, start bitcoind as follows: ```bash -stacks-node start --config=./testnet/stacks-node/conf/testnet-miner-conf.toml +bitcoind -conf=$HOME/bitcoin.conf ``` -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 -``` +:::note +It will take a few hours for the node to synchronize with Bitcoin testnet. +::: -The above code will compile an optimized binary. To use it, run: To use it, run: +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 -cd ../.. -cd ../.. -cd ../.. -./target/release/stacks-node start --config=./testnet/conf/testnet-follower-conf.toml +$ bitcoin-cli \ + -rpcconnect=localhost \ + -rpcport=18332 \ + -rpcuser=btcuser \ + -rpcpassword=btcpass \ +getblockchaininfo | jq .blocks +2417570 ``` -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 +## Running a Stacks Blockchain miner -### Prerequisites +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) -Make sure are [running a testnet node](run-a-node) before starting this tutorial. +_There may be some extra requirements to building, [defined here](https://github.com/stacksfoundation/miner-docs/blob/main/prerequisites.md#install-required-packages)_ -### Generate keychain and get testnet tokens in Windows +:::tip It is recommened to use a persistent location for the chainstate, in the steps below we're using `/stacks-blockchain` ::: -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. +### Generate a keychain -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. +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. -Generate a keychain: +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 -npm install --global @stacks/cli -stx make_keychain -t > cli_keychain.json -type cli_keychain.json +npx @stacks/cli make_keychain -t 2>/dev/null | jq -r ``` -After this runs, you'll probably see some installation logs, and at the end you should see some JSON that looks like this: +After this runs, you should see some JSON printed to the screen that looks like this: ```json { @@ -199,162 +112,110 @@ After this runs, you'll probably see some installation logs, and at the end you } ``` -:::tip Check out the [Stacks CLI reference](https://docs.hiro.so/references/stacks-cli) for more details ::: +:::warning **Do not lose this information** - we'll need to use the `privateKey` and `btcAddress` fields in later steps. ::: -Request BTC from faucet: +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 ::: -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. +```bash +bitcoin-cli \ + -rpcport=18332 \ + -rpcuser=btcuser \ + -rpcpassword=btcpassword \ +importaddress +``` -### Update configuration file +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. 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 Stacks Blockchain Configuration File -Update the following properties: +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`. -```toml -[node] -... -[node] -... -seed = "replace-with-your-private-key" -local_peer_seed = "replace-with-your-private-key" -... +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. -[burnchain] -... -[node] -... -seed = "replace-with-your-private-key" -local_peer_seed = "replace-with-your-private-key" -... +Next, update the bitcoin configuration: -[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 = "" -... +- **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`) -[burnchain] -... +```toml [node] -... -seed = "replace-with-your-private-key" -local_peer_seed = "replace-with-your-private-key" -... +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] -... -# To mine on Testnet, you need to run bitcoind locally -# Details can be found in above section, 'Running bitcoind locally' +chain = "bitcoin" +mode = "xenon" peer_host = "127.0.0.1" -username = "" -password = "" -... +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 ``` -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 +### Start the Stacks Blockchain -To start your miner, run this in the command line: +To run your miner, run this in the command line: ```bash -stacks-node start --config=testnet/stacks-node/conf/testnet-miner-conf.toml +stacks-node start --config=$HOME/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 +### 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 -set RUST_BACKTRACE=full; -set STACKS_LOG_DEBUG=1; -stacks-node start --config=testnet-miner-conf.toml +STACKS_LOG_DEBUG=1 stacks-node start --config=$HOME/testnet-miner-conf.toml ``` -## Optional: Running with Docker +--- + +## Optional: Running a Stacks Blockchain miner with Docker -Alternatively, you can run the testnet node with Docker. +Alternatively, you can run a Stacks testnet miner with Docker. -:::warning Ensure you have [Docker](https://docs.docker.com/get-docker/) installed on your machine. ::: ::: ::: +:::caution Ensure you have [Docker](https://docs.docker.com/get-docker/) installed ::: -### Generate keychain and get testnet tokens +### Generate a Keychain and Get Some Tokens Generate a keychain: ```bash -docker run -i node:14-alpine npx @stacks/cli make_keychain -t 2>/dev/null +docker run -i node:14-alpine npx @stacks/cli make_keychain 2>/dev/null | jq -r ``` -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" -... +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. -[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 = "" -... -``` +### Update Stacks Blockchain Docker Configuration File -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. +Use the steps oulined above to create the [configuration file](miner-testnet#update-the-stacks-blockchain-configuration-file) -### Start the miner +### 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 ::: If removed, debug logs will be disabled ::: @@ -365,7 +226,8 @@ docker run -d \ --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" \ + -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 \ @@ -378,26 +240,22 @@ You can review the node logs with this command: 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). +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 on your machine: +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 testnet tokens - -Generate a keychain: - -```bash -docker run -i node:14-alpine npx @stacks/cli make_keychain -t 2>/dev/null -``` +### Generate keychain and get some tokens -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. +Use the steps [outlined above](miner-testnet#generate-a-keychain-and-get-some-tokens) ### Install the chart and run the miner @@ -408,7 +266,7 @@ 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.node.seed="replace-with-your-privateKey-from-generate-keychain-step" \ ``` You can review the node logs with this command: From f08d42a218579a1a85a309569eb2ccfeeaf6b22b Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:44:53 +0100 Subject: [PATCH 0493/1444] New translations stacks-node-configuration.md (Chinese Simplified) --- .../stacks-node-configuration.md | 183 +++++++++++------- 1 file changed, 113 insertions(+), 70 deletions(-) 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 index ea9a1e45d3..4c432bc86b 100644 --- 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 @@ -1,7 +1,7 @@ --- title: Stacks Node Configuration description: Configuration parameters and options for the stacks-node binary -sidebar_position: 6 +sidebar_position: 4 --- ## Usage @@ -10,97 +10,141 @@ sidebar_position: 6 stacks-node sub-command [--subcommand-option ] ``` -## Subcommands +### 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 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 -### mocknet +## Configuration File Options -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. +The Stacks Blockchain configuration file has multiple sections under which an option may be placed. -Example: +- [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) -```bash -stacks-node mocknet -``` +For reference, several configuration file examples are [available here](https://github.com/stacks-network/stacks-blockchain/tree/master/testnet/stacks-node/conf) -### krypton +- [Example mainnet follower configuration](./stacks-node-configuration#example-mainnet-follower-configuration) -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 +### node -Example: +Contains various configuration options for the stacks-node binary. -```bash -stacks-node krypton -``` +| 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. | -### testnet +### events_observer -Start a node that will join and stream blocks from the public testnet. +:::info This section is _optional_ and not required -Example: +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. -```bash -stacks-node testnet -``` +| 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. 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. | | -### mainnet +### connection_options -Start a node that joins and streams blocks from the public mainnet. +:::info This section is _optional_ and not required. -Example: +However, if this section is added, **all** fields are required ::: -```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. +Specifies configuration options for others connecting to the stacks node. -#### Arguments +| 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 | -**--config**: relative or absolute path to the TOML config file. Required. Required. Required. +### burnchain -Example: +This section contains configuration options pertaining to the blockchain the stacks-node binds to on the backend for proof-of-transfer (BTC). -```bash -stacks-node start --config=/path/to/config.toml -``` +| Name | Required | Description | +| --------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| 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` | +| 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"`. 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` | -See [Configuration File Options](#configuration-file-options) for more information. +#### Mining -#### version +| 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`. | -Displays information about the current version and the release cycle. +### ustx_balance -Example: +- `mocknet`/`testnet` only -```bash -stacks-node version -``` +This section contains configuration options allocating microSTX per address in the genesis block -#### help +This section can repeat multiple times, but each section can only define a single address. -Displays a help message. +:::info This section is only required for the `testnet` and `mocknet` networks. -Example: +However, if this section is added, **all** fields are required ::: -```bash -stacks-node help -``` +| 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 | -## Configuration File Options +## Example Mainnet Follower Configuration -The TOML configuration file has multiple sections under which an option may be placed. +```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" -To see a list of example configurations, [please see this page](https://github.com/stacks-network/stacks-blockchain/tree/master/testnet/stacks-node/conf). +[burnchain] +chain = "bitcoin" +mode = "mainnet" +peer_host = "localhost" +username = "user" +password = "pass" +rpc_port = 8332 +peer_port = 8333 -### Section: node +[[events_observer]] +endpoint = "localhost:3700" +retry_count = 255 +events_keys = ["*"] +``` -Contains various configuration options pertaining to the stacks-node. -Example: + From 77334023b914054bb01c473c3b9a49c2464410c7 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:44:54 +0100 Subject: [PATCH 0494/1444] New translations accounts.md (Chinese Simplified) --- .../current/stacks-academy/accounts.md | 217 ++++++++++++++++++ 1 file changed, 217 insertions(+) create mode 100644 i18n/zh/docusaurus-plugin-content-docs/current/stacks-academy/accounts.md diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/stacks-academy/accounts.md b/i18n/zh/docusaurus-plugin-content-docs/current/stacks-academy/accounts.md new file mode 100644 index 0000000000..8942535ac4 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/current/stacks-academy/accounts.md @@ -0,0 +1,217 @@ +--- +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. 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 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, + 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). 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" + } + } + ] +} +``` From fd005787760c74c8b3975aa3f4b4e3b5c0a9cbb3 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:44:55 +0100 Subject: [PATCH 0495/1444] New translations microblocks.md (Chinese Simplified) --- .../current/stacks-academy/microblocks.md | 107 ++++++++++++++++++ 1 file changed, 107 insertions(+) create mode 100644 i18n/zh/docusaurus-plugin-content-docs/current/stacks-academy/microblocks.md diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/stacks-academy/microblocks.md b/i18n/zh/docusaurus-plugin-content-docs/current/stacks-academy/microblocks.md new file mode 100644 index 0000000000..17a84e4e12 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/current/stacks-academy/microblocks.md @@ -0,0 +1,107 @@ +--- +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. 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. + +#### 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. + +[provides an endpoint]: https://docs.hiro.so/get-started/stacks-blockchain-api#nonce-handling +[microblocks_api]: https://docs.hiro.so/api#tag/Microblocks From 11b5d117ba6ca690065e94acba2aadfa03a4cb03 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:44:56 +0100 Subject: [PATCH 0496/1444] New translations mining.md (Chinese Simplified) --- .../current/stacks-academy/mining.md | 84 +++++++++++++++++++ 1 file changed, 84 insertions(+) create mode 100644 i18n/zh/docusaurus-plugin-content-docs/current/stacks-academy/mining.md diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/stacks-academy/mining.md b/i18n/zh/docusaurus-plugin-content-docs/current/stacks-academy/mining.md new file mode 100644 index 0000000000..9150fcdac1 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/current/stacks-academy/mining.md @@ -0,0 +1,84 @@ +--- +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. 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) + +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 + +## 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 From 1d102ee2785a66c47578726bd01c68f139ee6df7 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:44:57 +0100 Subject: [PATCH 0497/1444] New translations network.md (Chinese Simplified) --- .../current/stacks-academy/network.md | 152 ++++++++++++++++++ 1 file changed, 152 insertions(+) create mode 100644 i18n/zh/docusaurus-plugin-content-docs/current/stacks-academy/network.md diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/stacks-academy/network.md b/i18n/zh/docusaurus-plugin-content-docs/current/stacks-academy/network.md new file mode 100644 index 0000000000..7826244499 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/current/stacks-academy/network.md @@ -0,0 +1,152 @@ +--- +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). 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 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 +} +``` From 30eb656f32ebfe60582fc2f5885ee5efe48e3fc6 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:44:58 +0100 Subject: [PATCH 0498/1444] New translations stacking.md (Chinese Simplified) --- .../current/stacks-academy/stacking.md | 151 ++++++++++++++++++ 1 file changed, 151 insertions(+) create mode 100644 i18n/zh/docusaurus-plugin-content-docs/current/stacks-academy/stacking.md diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/stacks-academy/stacking.md b/i18n/zh/docusaurus-plugin-content-docs/current/stacks-academy/stacking.md new file mode 100644 index 0000000000..b684266d47 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/current/stacks-academy/stacking.md @@ -0,0 +1,151 @@ +--- +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. 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. + +![](/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 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 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 + +## 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 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. 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) From 295892706547c16121f871c3185b842bfd976eac Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:44:58 +0100 Subject: [PATCH 0499/1444] New translations technical-specs.md (Chinese Simplified) --- .../current/stacks-academy/technical-specs.md | 79 +++++++++++++++++++ 1 file changed, 79 insertions(+) create mode 100644 i18n/zh/docusaurus-plugin-content-docs/current/stacks-academy/technical-specs.md diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/stacks-academy/technical-specs.md b/i18n/zh/docusaurus-plugin-content-docs/current/stacks-academy/technical-specs.md new file mode 100644 index 0000000000..3ecf4936a0 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/current/stacks-academy/technical-specs.md @@ -0,0 +1,79 @@ +--- +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). [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 whitepaper v2](https://www.youtube.com/watch?v=Wd-Bfe8Sn-Y). From 5216aa3232533dc76331e98122e80e4c33418eee Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:44:59 +0100 Subject: [PATCH 0500/1444] New translations testnet.md (Chinese Simplified) --- .../current/stacks-academy/testnet.md | 35 +++++++++++++++++++ 1 file changed, 35 insertions(+) create mode 100644 i18n/zh/docusaurus-plugin-content-docs/current/stacks-academy/testnet.md diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/stacks-academy/testnet.md b/i18n/zh/docusaurus-plugin-content-docs/current/stacks-academy/testnet.md new file mode 100644 index 0000000000..f8b9f03df2 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/current/stacks-academy/testnet.md @@ -0,0 +1,35 @@ +--- +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. + +### 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) From ecd16f15232e9b07e9728f70c53bda2c1cdf374a Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:45:00 +0100 Subject: [PATCH 0501/1444] New translations transactions.md (Chinese Simplified) --- .../current/stacks-academy/transactions.md | 40 +++++++++++++++++++ 1 file changed, 40 insertions(+) create mode 100644 i18n/zh/docusaurus-plugin-content-docs/current/stacks-academy/transactions.md diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/stacks-academy/transactions.md b/i18n/zh/docusaurus-plugin-content-docs/current/stacks-academy/transactions.md new file mode 100644 index 0000000000..8f44eb1d5f --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/current/stacks-academy/transactions.md @@ -0,0 +1,40 @@ +--- +title: Transactions +description: Guide to Stacks 2.0 transactions +sidebar_position: 9 +--- + +## 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). ::: From a91ec573d3d82069e55540baf59e3e666bc2bfbd Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:45:02 +0100 Subject: [PATCH 0502/1444] New translations language-functions.md (Chinese Simplified) --- .../current/clarity/language-functions.md | 2032 +++++++++++++++++ 1 file changed, 2032 insertions(+) create mode 100644 i18n/zh/docusaurus-plugin-content-docs/current/clarity/language-functions.md diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/clarity/language-functions.md b/i18n/zh/docusaurus-plugin-content-docs/current/clarity/language-functions.md new file mode 100644 index 0000000000..b61ee10ae6 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/current/clarity/language-functions.md @@ -0,0 +1,2032 @@ +--- +title: Functions +description: See a detailed list of all functions for the Clarity language. +sidebar_position: 3 +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: + +#### 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 +``` + +### 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-existent\"))))) ;; 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-existent\") ;; 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-existent\" })) ;; 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-existent\" }))) ;; 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-existent\" }))) ;; 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 \"Stacks\" '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 successfully 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_ transferred 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 successfully 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_ transferred 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 successfully 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 successfully 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)) +``` From 07d6dc767a4b98518fb9836d39c7fc4a6c6b3198 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:45:03 +0100 Subject: [PATCH 0503/1444] New translations language-keywords.md (Chinese Simplified) --- .../current/clarity/language-keywords.md | 146 ++++++++++++++++++ 1 file changed, 146 insertions(+) create mode 100644 i18n/zh/docusaurus-plugin-content-docs/current/clarity/language-keywords.md diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/clarity/language-keywords.md b/i18n/zh/docusaurus-plugin-content-docs/current/clarity/language-keywords.md new file mode 100644 index 0000000000..45608736a5 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/current/clarity/language-keywords.md @@ -0,0 +1,146 @@ +--- +title: Keywords +description: See a detailed list of all keywords for the Clarity language. +sidebar_position: 4 +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 +``` From 93987a1fbc16f96843e8bb050b1f3e592e00ccea Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:45:04 +0100 Subject: [PATCH 0504/1444] New translations language-types.md (Chinese Simplified) --- .../current/clarity/language-types.md | 25 +++++++++++++++++++ 1 file changed, 25 insertions(+) create mode 100644 i18n/zh/docusaurus-plugin-content-docs/current/clarity/language-types.md diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/clarity/language-types.md b/i18n/zh/docusaurus-plugin-content-docs/current/clarity/language-types.md new file mode 100644 index 0000000000..3973afbaeb --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/current/clarity/language-types.md @@ -0,0 +1,25 @@ +--- +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. 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. | From 43333d055f1e413a081c8df42129fd5dcf6eb5cc Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:45:05 +0100 Subject: [PATCH 0505/1444] New translations miner-costs-and-fees.md (Chinese Simplified) --- .../current/nodes-and-miners/miner-costs-and-fees.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) 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 index 40397a51e0..dd8ee721cc 100644 --- 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 @@ -8,7 +8,7 @@ sidebar_position: 8 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 @@ -22,3 +22,5 @@ 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). From 04de2890475d6cb9dbc594be9340c1cb19659e1a Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:45:06 +0100 Subject: [PATCH 0506/1444] New translations verify-miner.md (Chinese Simplified) --- .../current/nodes-and-miners/verify-miner.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) 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 index 094e3f03a1..18e8dd3a48 100644 --- 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 @@ -7,7 +7,7 @@ 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 +$ 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 -``` \ No newline at end of file +``` From fa8899c725a85c64fe33a2b030414309aabd1aac Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:45:07 +0100 Subject: [PATCH 0507/1444] New translations stacks-blockchain-api.md (Chinese Simplified) --- .../stacks-academy/stacks-blockchain-api.md | 41 +++++++++++++++++++ 1 file changed, 41 insertions(+) create mode 100644 i18n/zh/docusaurus-plugin-content-docs/current/stacks-academy/stacks-blockchain-api.md diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/stacks-academy/stacks-blockchain-api.md b/i18n/zh/docusaurus-plugin-content-docs/current/stacks-academy/stacks-blockchain-api.md new file mode 100644 index 0000000000..e8418e1b03 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/current/stacks-academy/stacks-blockchain-api.md @@ -0,0 +1,41 @@ +--- +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. 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. + +:::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). ::: :::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). ::: ::: + +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. 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. + +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`. ::: ::: From ca69bdf6e2b290739e104f3a2c85275e69ee0427 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:45:08 +0100 Subject: [PATCH 0508/1444] New translations run-a-node.md (Chinese Simplified) --- .../current/nodes-and-miners/run-a-node.md | 329 +++--------------- 1 file changed, 42 insertions(+), 287 deletions(-) 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 index 94d938c5ca..2993568ce4 100644 --- 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 @@ -1,5 +1,5 @@ --- -title: Run a node +title: Run a Node with Docker description: Set up and run a Stacks node sidebar_position: 1 tags: @@ -8,344 +8,99 @@ tags: ## Stacks Blockchain with Docker -Run your own Stacks Blockchain node easily with just few commands. +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) -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](./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) -## **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 -``` +## **Requirements:** -- With optional proxy: +The **minimum viable requirements** are listed below. -```bash -./manage.sh -n -a start -f proxy -``` +While you _can_ run a node using these specs, it's _recommended_ to assign more than the minimum for better performance. -- With optional bitcoin node: +- ⚠️ [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_ ) -```bash -./manage.sh -n -a start -f bitcoin -``` +:::caution MacOS with an ARM processor is NOT recommended -5. **Stop the Services** +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. ::: -```bash -./manage.sh -n -a stop -``` - -6. **Retrieve Service Logs** - -```bash -./manage.sh -n -a logs -``` - -- Export docker log files to `./exported-logs`: +## **Quickstart** -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. +The `` placeholder used below can be replaced with one of: -```bash -./manage.sh -n -a logs export -``` +- mainnet +- testnet +- mocknet -7. **Restart all services** +1. **Clone the stacks-blockchain-docker repository locally** ```bash -./manage.sh -n -a restart +git clone https://github.com/stacks-network/stacks-blockchain-docker && cd stacks-blockchain-docker ``` -- With optional proxy: +2. **Start the Services** ```bash -./manage.sh -n -a restart -f proxy +./manage.sh -n -a start ``` -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. +:::note With an optional HTTP proxy on port 80: ```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. - +./manage.sh -n -a start -f proxy ``` -9. **Download BNS data to** `./persistent-data/bns-data` - -```bash -./manage.sh bns -``` +::: -10. **Export stacks-blockchain-api events** (_Not applicable for mocknet_) +## **Accessing the services** -```bash -./manage.sh -n -a export -# check logs for completion -./manage.sh -n -a restart -``` +:::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. -11. **Replay stacks-blockchain-api events** (_Not applicable for mocknet_) +Follow the logs to track the sync progress: ```bash -./manage.sh -n -a import -# check logs for completion -./manage.sh -n -a restart +./manage.sh -n -a logs ``` -## **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` +- Ports `20443-20444` are exposed on `localhost` ```bash -curl -sL localhost:20443/v2/info | jq +curl -sL localhost:20443/v2/info | jq -r ``` **stacks-blockchain-api**: -- Port `3999` are exposed to `localhost` +- Port `3999` is exposed on `localhost` ```bash -curl -sL localhost:3999/v2/info | jq +curl -sL localhost:3999 | jq -r ``` **proxy**: -- Port `80` is exposed to `localhost` +- Port `80` is exposed on `localhost` ```bash -curl -sL localhost/v2/info | jq -curl -sL localhost/ | jq +curl -sL localhost/v2/info | jq -r +curl -sL localhost | jq -r ``` --- ## 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 -``` +:::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): ::: --- - -## **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 From 13f9a5fa68d3ed3018d89f8dad628fcef1de9308 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:45:09 +0100 Subject: [PATCH 0509/1444] New translations index.md (Chinese Simplified) --- .../current/clarity/index.md | 58 +++++++++++++++++++ 1 file changed, 58 insertions(+) create mode 100644 i18n/zh/docusaurus-plugin-content-docs/current/clarity/index.md diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/clarity/index.md b/i18n/zh/docusaurus-plugin-content-docs/current/clarity/index.md new file mode 100644 index 0000000000..0d409aecb4 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/current/clarity/index.md @@ -0,0 +1,58 @@ +--- +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. 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?2 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. If you are unsure what this means, let it not worry you for now. The serious advantage of decidability will become more apparent over time. + +### 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. From 527b84c44e72914e2c0239654ded866e9a704d75 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:45:10 +0100 Subject: [PATCH 0510/1444] New translations index.md (Chinese Simplified) --- .../current/stacks-academy/index.md | 11 +++++++++++ 1 file changed, 11 insertions(+) create mode 100644 i18n/zh/docusaurus-plugin-content-docs/current/stacks-academy/index.md diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/stacks-academy/index.md b/i18n/zh/docusaurus-plugin-content-docs/current/stacks-academy/index.md new file mode 100644 index 0000000000..a5bdb3c790 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/current/stacks-academy/index.md @@ -0,0 +1,11 @@ +--- +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. From f6f62034ea1e5a5b3afb5ce7e2c04f937fafd68a Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:45:11 +0100 Subject: [PATCH 0511/1444] New translations proof-of-transfer.md (Chinese Simplified) --- .../stacks-academy/proof-of-transfer.md | 83 +++++++++++++++++++ 1 file changed, 83 insertions(+) create mode 100644 i18n/zh/docusaurus-plugin-content-docs/current/stacks-academy/proof-of-transfer.md diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/stacks-academy/proof-of-transfer.md b/i18n/zh/docusaurus-plugin-content-docs/current/stacks-academy/proof-of-transfer.md new file mode 100644 index 0000000000..5697840907 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/current/stacks-academy/proof-of-transfer.md @@ -0,0 +1,83 @@ +--- +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. 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 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, proof-of-transfer blockchains are anchored on their chosen proof-of-work chain. Stacks uses [Bitcoin](#why-bitcoin) as its anchor chain. 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. 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 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. 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 + +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. From 08bfa1279edb0867da54a71d0eff08eb360c7b41 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:45:11 +0100 Subject: [PATCH 0512/1444] New translations what-is-stacks.md (Chinese Simplified) --- .../current/stacks-academy/what-is-stacks.md | 102 ++++++++++++++++++ 1 file changed, 102 insertions(+) create mode 100644 i18n/zh/docusaurus-plugin-content-docs/current/stacks-academy/what-is-stacks.md diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/stacks-academy/what-is-stacks.md b/i18n/zh/docusaurus-plugin-content-docs/current/stacks-academy/what-is-stacks.md new file mode 100644 index 0000000000..94277da8a9 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/current/stacks-academy/what-is-stacks.md @@ -0,0 +1,102 @@ +--- +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. + +There's a lot of jargon, possible assumptions, controversy, and cool technology wrapped up in those statements. So let's get started by getting a 30,000 foot view of what exactly Stacks is. + +## Stacks Explained in (Slightly Less Than) 10 Minutes + +
+ +
+ +## 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, Stacks takes a different approach. + +## 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). + +By taking this 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 with some unique properties, like having its own token, that allow it to maintain a historical ledger of all of its transactions and operate with its own security budget. + +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_. + +Nope. 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. From 343d6c4bf381679a2c09e5d27994735e089aaa8d Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:45:12 +0100 Subject: [PATCH 0513/1444] New translations community-tutorials.md (Chinese Simplified) --- .../current/tutorials/community-tutorials.md | 24 +++++++++++++++++++ 1 file changed, 24 insertions(+) create mode 100644 i18n/zh/docusaurus-plugin-content-docs/current/tutorials/community-tutorials.md diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/tutorials/community-tutorials.md b/i18n/zh/docusaurus-plugin-content-docs/current/tutorials/community-tutorials.md new file mode 100644 index 0000000000..a4f3d970ca --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/current/tutorials/community-tutorials.md @@ -0,0 +1,24 @@ +--- +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/) From 30196e5020074cac677705c4bf30d3d40aac6b5d Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:45:13 +0100 Subject: [PATCH 0514/1444] New translations hello-stacks.md (Chinese Simplified) --- .../current/tutorials/hello-stacks.md | 759 ++++++++++++++++++ 1 file changed, 759 insertions(+) create mode 100644 i18n/zh/docusaurus-plugin-content-docs/current/tutorials/hello-stacks.md diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/tutorials/hello-stacks.md b/i18n/zh/docusaurus-plugin-content-docs/current/tutorials/hello-stacks.md new file mode 100644 index 0000000000..a0a442d135 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/current/tutorials/hello-stacks.md @@ -0,0 +1,759 @@ +--- +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. From 8f5abf42b2288610ffb8fde0a363a395dc367f2b Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:45:14 +0100 Subject: [PATCH 0515/1444] New translations index.md (Chinese Simplified) --- .../current/tutorials/index.md | 11 +++++++++++ 1 file changed, 11 insertions(+) create mode 100644 i18n/zh/docusaurus-plugin-content-docs/current/tutorials/index.md diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/tutorials/index.md b/i18n/zh/docusaurus-plugin-content-docs/current/tutorials/index.md new file mode 100644 index 0000000000..1d544c7bc1 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/current/tutorials/index.md @@ -0,0 +1,11 @@ +--- +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. From e2daebcfc03d2c14fb6ff2a5b884b754232199fd Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:45:15 +0100 Subject: [PATCH 0516/1444] New translations satoshis-ridge.md (Chinese Simplified) --- .../current/tutorials/satoshis-ridge.md | 75 +++++++++++++++++++ 1 file changed, 75 insertions(+) create mode 100644 i18n/zh/docusaurus-plugin-content-docs/current/tutorials/satoshis-ridge.md diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/tutorials/satoshis-ridge.md b/i18n/zh/docusaurus-plugin-content-docs/current/tutorials/satoshis-ridge.md new file mode 100644 index 0000000000..596339ae74 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/current/tutorials/satoshis-ridge.md @@ -0,0 +1,75 @@ +--- +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 arguable one of its strengths. + +Instead, we need to create separate layers that add additional functionality without modify 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. From 4b4ab5a60cdb01e1f8ccc4717ae9ee28ae935ac8 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:45:15 +0100 Subject: [PATCH 0517/1444] New translations crash-course.md (Chinese Simplified) --- .../current/clarity/crash-course.md | 122 ++++++++++++++++++ 1 file changed, 122 insertions(+) create mode 100644 i18n/zh/docusaurus-plugin-content-docs/current/clarity/crash-course.md diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/clarity/crash-course.md b/i18n/zh/docusaurus-plugin-content-docs/current/clarity/crash-course.md new file mode 100644 index 0000000000..5b27a3c275 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/current/clarity/crash-course.md @@ -0,0 +1,122 @@ +--- +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.md). + +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. + +```clojure +(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: + +```clojure +(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. From cfcd571ed53967a4c1bb3416fef376fc60099fe0 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:45:16 +0100 Subject: [PATCH 0518/1444] New translations sample-contracts.md (Chinese Simplified) --- .../current/clarity/sample-contracts.md | 14 ++++++++++++++ 1 file changed, 14 insertions(+) create mode 100644 i18n/zh/docusaurus-plugin-content-docs/current/clarity/sample-contracts.md diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/clarity/sample-contracts.md b/i18n/zh/docusaurus-plugin-content-docs/current/clarity/sample-contracts.md new file mode 100644 index 0000000000..adb12a58fd --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/current/clarity/sample-contracts.md @@ -0,0 +1,14 @@ +--- +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) From 333c0d7df6f27cc1600aa745cb208990d2856644 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:45:17 +0100 Subject: [PATCH 0519/1444] New translations index.md (Chinese Simplified) --- .../current/cookbook/index.md | 64 +++++++++++++++++++ 1 file changed, 64 insertions(+) create mode 100644 i18n/zh/docusaurus-plugin-content-docs/current/cookbook/index.md diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/cookbook/index.md b/i18n/zh/docusaurus-plugin-content-docs/current/cookbook/index.md new file mode 100644 index 0000000000..a2b0e42eea --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/current/cookbook/index.md @@ -0,0 +1,64 @@ +--- +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 + +Swapping between Bitcoin and Stacks addresses + +Swapping between xBTC and BTC + +Verifying a transaction on the BTC chain + +## 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 + +Airdropping an NFT to a Bitcoin address + +## Stacking and Mining + +Simple stacking pool + +Continuous stacking + +Simple mining pool + +Proof of PoX payout + +## Oracles + +Creating a simple BTC price oracle + +## Frontend + +[Post conditions with Stacks.js](./post-conditions) + +[Authentication with Stacks.js](./stacks-js-auth) + +[Sending transactions with Stacks.js](./stacks-js-sending-transactions) + +## Complete Apps + +[Sup](https://github.com/kenrogers/sup) + +[Hello Stacks](https://github.com/kenrogers/hello-stacks) From 24cbe4c3e98f25a37967f1b8364de0c5f10b0f1a Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:45:18 +0100 Subject: [PATCH 0520/1444] New translations btc-connection.md (Chinese Simplified) --- .../current/stacks-academy/btc-connection.md | 196 ++++++++++++++++++ 1 file changed, 196 insertions(+) create mode 100644 i18n/zh/docusaurus-plugin-content-docs/current/stacks-academy/btc-connection.md diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/stacks-academy/btc-connection.md b/i18n/zh/docusaurus-plugin-content-docs/current/stacks-academy/btc-connection.md new file mode 100644 index 0000000000..b4db915969 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/current/stacks-academy/btc-connection.md @@ -0,0 +1,196 @@ +--- +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. + +## Stacks Among Other Bitcoin Layers + +In the [last section](./what-is-stacks.md) we covered what Stacks actually is and what problem it is solving, but this is not a new problem. The Bitcoin write problem has been a bit of a holy grail problem in the crypto world for a while now. + +Bitcoin is the OG cryptocurrency and has the largest market cap, but it also some of the least functionality, which means if we want to make it a productive asset and use it to build a decentralized economy, we need to take a layered approach and let Bitcoin do what it does best, while creating additional layers on top of it to add functionality. + +So how does Stacks compare to some of the other approaches to layering on top of Bitcoin? + +### 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. + +## 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. + +But because it has its own execution environment and smart contract state to maintain, it needs a token to incentivize maintenance of the network. + +But it goes further than that. It is possible to build a system like this without a token using something like merge-mining or a sidechain, but then we lose out on the additional benefit of having the chain state's safety underpinned by its entire token economy's value. + +In the case of Stacks, the safety and liveness of the chain are underpinned by this value, and the stacking mechanism incentivizes network members to increase this value. + +From Jude Nelson, Stacks core developer: + +"How hard is it to cause a safety failure (i.e. a double-spend via a reorg) on just the canonical Stacks chain fork? Anyone can become a miner by spending BTC, so without loss of generality, reverting the last block on the canonical chain is at least as hard in expectation as spending more BTC than the rest of the miners combined for that block. Because each Bitcoin block selects at most one Stacks block, the act of reorging the canonical Stacks chain back N blocks is the act of winning at least N + 1 blocks built off of a common ancestor that is N blocks deep. This is a lower bound on the number of Bitcoin blocks mined during which a reorg needs to take place — in practice, honest miners will keep working on the canonical chain, and will win some Stacks blocks of their own, which in turn increases the number of Stacks blocks the reorging miners must win. + +How costly is it to carry out a reorg of N blocks? It’s a function of how valuable STX is relative to BTC — the more valuable STX are, the more BTC honest miners are committing to mining (this has borne out in practice), and thus the more BTC a reorging miner must commit. Therefore, the cost of a reorg is a function of the value of STX. + +This is similar to the economic security of a PoW blockchain. Like in PoW, each fork of the Stacks chain has its own independent “security budget” — an attacker must out-spend the security budget to carry out a reorg, and the security budget is a function of the block rewards. In PoX, the only difference is that the miners spend another blockchain’s tokens (BTC in Stacks’ case) instead of energy. Therefore, Stacks can’t be a sidechain, a drivechain, or a merge-mined chain, because none of these other systems’ security budgets are a function of their tokens’ worth. Sidechains, drivechains, and merged-mined chains all rely on external miners for their safety, since their safety is guaranteed in part by external miners validating their blocks. The onus on these systems is to get external miners to care enough to do so, and in the case of sidechains, drivechains, and blind merged-mined chains, there is an additional onus to encourage their nodes to mine blocks at all (since there is no on-chain reward for them to earn by doing so). By contrast, disinterested Bitcoin miners neither assist nor prevent a reorg in PoX — they only record the history of all Stacks forks. + +PoX offers two additional, unique security properties on top of PoW. First, no matter how much BTC a reorging miner can commit, the act of executing a reorg is going to be time-consuming. Unless the attacker can attack the Bitcoin chain itself by quickly producing a better Bitcoin fork, a reorging miner must sustain the attack for at least N + 1 Bitcoin blocks. This gives honest miners and users ample time to notice and react to the reorg attempt. + +Second, the history of block production in all Stacks forks is embedded within Bitcoin. This allows the system to leverage Bitcoin’s security budget in order to ensure that all forks are public. This is because the act of producing a hidden Stacks fork, where the fork’s block hashes are not known to the honest miners, is the act of producing a hidden canonical Bitcoin fork. Therefore, the act of producing a hidden Stacks fork is at least as hard as reorging the Bitcoin chain. A PoX chain leverages this property not to prevent reorgs, but to make reorgs unprofitable. + +By anchoring blocks to an existing blockchain, a PoX chain forces reorgs to happen out in the open, thereby giving advance warning to all honest network participants when they happen. Honest miners, users, and exchanges will see the PoX transactions for reorg attempts on the existing blockchain, and adapt their behaviors accordingly: honest miners will increase their commitments, and users and exchanges will require more confirmations for transactions. This makes the act of carrying out a reorg while also making a profit much more challenging, since malicious reorgs — like selfish mining and double-spending — rely on secrecy to work effectively. Specific to Stacks, miners are additionally required to mine for a “warm-up” period of two blocks, during which they must spend BTC at their target commit levels but will not win any Stacks blocks. So, a high-budget reorg attempt will not only be costly, but will also alert the rest of the network before the damage is done." + +- [What Kind of Blockchain is Stacks?](https://stacks.org/stacks-blockchain) + +## 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) From 183679b726fd8b72fa0ae30cee51aa16d6821cde Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:45:19 +0100 Subject: [PATCH 0521/1444] New translations post-conditions.md (Chinese Simplified) --- .../current/stacks-academy/post-conditions.md | 39 +++++++++++++++++++ 1 file changed, 39 insertions(+) create mode 100644 i18n/zh/docusaurus-plugin-content-docs/current/stacks-academy/post-conditions.md diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/stacks-academy/post-conditions.md b/i18n/zh/docusaurus-plugin-content-docs/current/stacks-academy/post-conditions.md new file mode 100644 index 0000000000..bb0727194f --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/current/stacks-academy/post-conditions.md @@ -0,0 +1,39 @@ +--- +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). From 62cd27be1cec9c92b153af3ee64f0a18038d282c Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:45:20 +0100 Subject: [PATCH 0522/1444] New translations creating-an-ft.md (Chinese Simplified) --- .../current/cookbook/creating-an-ft.md | 99 +++++++++++++++++++ 1 file changed, 99 insertions(+) create mode 100644 i18n/zh/docusaurus-plugin-content-docs/current/cookbook/creating-an-ft.md diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/cookbook/creating-an-ft.md b/i18n/zh/docusaurus-plugin-content-docs/current/cookbook/creating-an-ft.md new file mode 100644 index 0000000000..4e3bad99d2 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/current/cookbook/creating-an-ft.md @@ -0,0 +1,99 @@ +--- +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) + ) +) +``` From b73fdb75a50ce27cd5040aa7478c2bdc13dfedca Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:45:21 +0100 Subject: [PATCH 0523/1444] New translations creating-an-nft.md (Chinese Simplified) --- .../current/cookbook/creating-an-nft.md | 87 +++++++++++++++++++ 1 file changed, 87 insertions(+) create mode 100644 i18n/zh/docusaurus-plugin-content-docs/current/cookbook/creating-an-nft.md diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/cookbook/creating-an-nft.md b/i18n/zh/docusaurus-plugin-content-docs/current/cookbook/creating-an-nft.md new file mode 100644 index 0000000000..08faf9393a --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/current/cookbook/creating-an-nft.md @@ -0,0 +1,87 @@ +--- +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 +Code for this recipe has been pulled from [this NFT tutorial](https://blog.developerdao.com/building-an-nft-with-stacks-and-clarity) from Developer DAO. +::: + +## 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) + ) +) +``` From 68e3d5bc501f5549192f09d3f50890a4bea957a8 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:45:21 +0100 Subject: [PATCH 0524/1444] New translations post-conditions.md (Chinese Simplified) --- .../current/cookbook/post-conditions.md | 136 ++++++++++++++++++ 1 file changed, 136 insertions(+) create mode 100644 i18n/zh/docusaurus-plugin-content-docs/current/cookbook/post-conditions.md diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/cookbook/post-conditions.md b/i18n/zh/docusaurus-plugin-content-docs/current/cookbook/post-conditions.md new file mode 100644 index 0000000000..571fc20d48 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/current/cookbook/post-conditions.md @@ -0,0 +1,136 @@ +--- +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. From 4c9052f76766cf01c645c243221e81593aeeb3dd Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:45:22 +0100 Subject: [PATCH 0525/1444] New translations stacks-js-auth.md (Chinese Simplified) --- .../current/cookbook/stacks-js-auth.md | 98 +++++++++++++++++++ 1 file changed, 98 insertions(+) create mode 100644 i18n/zh/docusaurus-plugin-content-docs/current/cookbook/stacks-js-auth.md diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/cookbook/stacks-js-auth.md b/i18n/zh/docusaurus-plugin-content-docs/current/cookbook/stacks-js-auth.md new file mode 100644 index 0000000000..89d1f06e00 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/current/cookbook/stacks-js-auth.md @@ -0,0 +1,98 @@ +--- +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 && ( + + ); +} +``` From 26232d6eead53634552918574863db20725d888d Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:45:23 +0100 Subject: [PATCH 0526/1444] New translations stacks-js-sending-transactions.md (Chinese Simplified) --- .../stacks-js-sending-transactions.md | 55 +++++++++++++++++++ 1 file changed, 55 insertions(+) create mode 100644 i18n/zh/docusaurus-plugin-content-docs/current/cookbook/stacks-js-sending-transactions.md diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/cookbook/stacks-js-sending-transactions.md b/i18n/zh/docusaurus-plugin-content-docs/current/cookbook/stacks-js-sending-transactions.md new file mode 100644 index 0000000000..849c7d1f42 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/current/cookbook/stacks-js-sending-transactions.md @@ -0,0 +1,55 @@ +--- +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. From 4328b2921688d5e713500ac14099da141c1f5d21 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:45:24 +0100 Subject: [PATCH 0527/1444] New translations _category_.json (Chinese Simplified) --- .../current/clarity/noteworthy-contracts/_category_.json | 8 ++++++++ 1 file changed, 8 insertions(+) create mode 100644 i18n/zh/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/_category_.json diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/_category_.json b/i18n/zh/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/_category_.json new file mode 100644 index 0000000000..f5de305558 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/_category_.json @@ -0,0 +1,8 @@ +{ + "label": "Noteworthy Contracts", + "position": 4, + "link": { + "type": "generated-index", + "description": "Specific deployed Clarity Contracts worth mentioning." + } +} \ No newline at end of file From 32d38a23e45cd32bb93bfc578e72ca285103ec74 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:45:25 +0100 Subject: [PATCH 0528/1444] New translations bns-contract.md (Chinese Simplified) --- .../noteworthy-contracts/bns-contract.md | 519 ++++++++++++++++++ 1 file changed, 519 insertions(+) create mode 100644 i18n/zh/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/bns-contract.md diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/bns-contract.md b/i18n/zh/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/bns-contract.md new file mode 100644 index 0000000000..a7770b7d24 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/bns-contract.md @@ -0,0 +1,519 @@ +--- +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 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` From 87c68b5df50ee7dde80647e5e8be6a4d5b3904cf Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:45:26 +0100 Subject: [PATCH 0529/1444] New translations xbtc.md (Chinese Simplified) --- .../clarity/noteworthy-contracts/xbtc.md | 28 +++++++++++++++++++ 1 file changed, 28 insertions(+) create mode 100644 i18n/zh/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/xbtc.md diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/xbtc.md b/i18n/zh/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/xbtc.md new file mode 100644 index 0000000000..e535dcf260 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/xbtc.md @@ -0,0 +1,28 @@ +--- +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) From 1d65fc54fe14c667eb2f20b64e868d22a03ed163 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:45:27 +0100 Subject: [PATCH 0530/1444] New translations index.md (Chinese Simplified) --- .../current/glossary/index.md | 284 ++++++++++++++++++ 1 file changed, 284 insertions(+) create mode 100644 i18n/zh/docusaurus-plugin-content-docs/current/glossary/index.md diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/glossary/index.md b/i18n/zh/docusaurus-plugin-content-docs/current/glossary/index.md new file mode 100644 index 0000000000..419c0e0d73 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/current/glossary/index.md @@ -0,0 +1,284 @@ +--- +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. From 6b2c2a15a0ce09df8ff7e25718761e9c32fe1068 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:45:28 +0100 Subject: [PATCH 0531/1444] New translations quicknode.md (Chinese Simplified) --- .../current/nodes-and-miners/quicknode.md | 45 +++++++++++++++++++ 1 file changed, 45 insertions(+) create mode 100644 i18n/zh/docusaurus-plugin-content-docs/current/nodes-and-miners/quicknode.md diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/nodes-and-miners/quicknode.md b/i18n/zh/docusaurus-plugin-content-docs/current/nodes-and-miners/quicknode.md new file mode 100644 index 0000000000..1281964689 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/current/nodes-and-miners/quicknode.md @@ -0,0 +1,45 @@ +--- +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. From ab7a36ce4a52b9ffff2140ee5003c6f0d44185b3 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:45:29 +0100 Subject: [PATCH 0532/1444] New translations defi.md (Chinese Simplified) --- .../current/services-using-stacks/defi.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) 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 index c3fc0556bf..58717a3234 100644 --- 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 @@ -8,7 +8,7 @@ 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 @@ -26,7 +26,7 @@ Please edit this page to add any relevant new site that we are missing. ## Lnswap -[LNSWAP](https://www.lnswap.org). Non custiodial crypto currency exchange Non custiodial crypto currency exchange +[LNSWAP](https://www.lnswap.org). Non-custodial crypto currency exchange ![](/img/sh_lnswap.png) @@ -41,4 +41,3 @@ Please edit this page to add any relevant new site that we are missing. [Stackswap](https://app.stackswap.org/v2) ![](/img/sh_stackswap.png) - From 4f0e3a5095cfcdfc06f4479ba8ecfaf3ca85238d Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:45:30 +0100 Subject: [PATCH 0533/1444] New translations more.md (Chinese Simplified) --- .../current/services-using-stacks/more.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) 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 index a7b57f922c..1e14b9a5a5 100644 --- 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 @@ -8,7 +8,7 @@ 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 @@ -18,6 +18,6 @@ Please edit this page to add any relevant new site that we are missing. ## Sigle -[Sigle](https://www.sigle.io/) is a decentralised and open source web 3 writing platform. +[Sigle](https://www.sigle.io/) is a decentralized and open source web 3 writing platform. -![](/img/sh_sigle.png) \ No newline at end of file +![](/img/sh_sigle.png) From 832ae65fd2f3b6b672d58bc114e7b6e34c966c4d Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:45:30 +0100 Subject: [PATCH 0534/1444] New translations nft.md (Chinese Simplified) --- .../current/services-using-stacks/nft.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) 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 index c228a773d5..d582604854 100644 --- 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 @@ -8,13 +8,14 @@ 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/) @@ -35,4 +36,4 @@ Please edit this page to add any relevant new site that we are missing. ### [Superfandom](https://superfandom.io/) -![website-screenshot](/img/sh_superfandom.png) \ No newline at end of file +![website-screenshot](/img/sh_superfandom.png) From 6611afa557eb4e8f1fe7b127b67310a1d0640401 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:45:31 +0100 Subject: [PATCH 0535/1444] New translations stacks-info-sites.md (Chinese Simplified) --- .../current/services-using-stacks/stacks-info-sites.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) 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 index 9618006777..54f6823e33 100644 --- 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 @@ -8,7 +8,7 @@ A list of sites on alphabetical order that display status and stats of the Stack :::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) @@ -30,7 +30,7 @@ Please edit this page to add any relevant new site that we are missing. ![website-screenshot](/img/sh_stxstats.png) -### [Novuminsights](https://stacks.novuminsights.com/health) +### [Novum Insights](https://stacks.novuminsights.com/health) ![website-screenshot](/img/sh_novuminsights.png) From 1b768a5f9d05fb52c7c17948350f8900e4000b42 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:45:32 +0100 Subject: [PATCH 0536/1444] New translations wallets.md (Chinese Simplified) --- .../current/services-using-stacks/wallets.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) 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 index fb1bf958be..2d3fcc85f2 100644 --- 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 @@ -8,13 +8,14 @@ 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) @@ -26,6 +27,7 @@ Please edit this page to add any relevant new site that we are missing. [D'CENT](https://dcentwallet.com) ![](/img/sh_dcent.png) + ## Hiro Wallet [Hiro Wallet](https://www.hiro.so/wallet) @@ -48,4 +50,4 @@ Please edit this page to add any relevant new site that we are missing. [Wise](https://wiseapp.id) -![](/img/sh_wiseapp.png) \ No newline at end of file +![](/img/sh_wiseapp.png) From e8d92e32b0d25ee8722b926d337165a9b3f833f4 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:45:33 +0100 Subject: [PATCH 0537/1444] New translations whitepapers.md (Chinese Simplified) --- .../current/stacks-academy/whitepapers.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) create mode 100644 i18n/zh/docusaurus-plugin-content-docs/current/stacks-academy/whitepapers.md diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/stacks-academy/whitepapers.md b/i18n/zh/docusaurus-plugin-content-docs/current/stacks-academy/whitepapers.md new file mode 100644 index 0000000000..0e564fbf44 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/current/stacks-academy/whitepapers.md @@ -0,0 +1,12 @@ +--- +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) From f5cc1a3414b108d989fd1b02cfbcc0f0548a5fe3 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:45:34 +0100 Subject: [PATCH 0538/1444] New translations stacking-contract.md (Chinese Simplified) --- .../noteworthy-contracts/stacking-contract.md | 352 ++++++++++++++++++ 1 file changed, 352 insertions(+) create mode 100644 i18n/zh/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/stacking-contract.md diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/stacking-contract.md b/i18n/zh/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/stacking-contract.md new file mode 100644 index 0000000000..c0027256cd --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/stacking-contract.md @@ -0,0 +1,352 @@ +--- +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. 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` From 494178790502644191fb2ba4452b18c605f1bc83 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:45:35 +0100 Subject: [PATCH 0539/1444] New translations index.md (Chinese Simplified) --- .../current/next-steps/index.md | 39 +++++++++++++++++++ 1 file changed, 39 insertions(+) create mode 100644 i18n/zh/docusaurus-plugin-content-docs/current/next-steps/index.md diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/next-steps/index.md b/i18n/zh/docusaurus-plugin-content-docs/current/next-steps/index.md new file mode 100644 index 0000000000..00ddec9178 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/current/next-steps/index.md @@ -0,0 +1,39 @@ +--- +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) From aabd7ebd164ccec02541bb5fc2c37ebda9d7a2a1 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:45:36 +0100 Subject: [PATCH 0540/1444] New translations sips.md (Chinese Simplified) --- .../current/stacks-academy/sips.md | 52 +++++++++++++++++++ 1 file changed, 52 insertions(+) create mode 100644 i18n/zh/docusaurus-plugin-content-docs/current/stacks-academy/sips.md diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/stacks-academy/sips.md b/i18n/zh/docusaurus-plugin-content-docs/current/stacks-academy/sips.md new file mode 100644 index 0000000000..aa2db18e62 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/current/stacks-academy/sips.md @@ -0,0 +1,52 @@ +--- +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/IJ15791776) 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-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. From bc53118ad0aa11209225b47160fdb6f520f00fea Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:45:36 +0100 Subject: [PATCH 0541/1444] New translations hosted-nodes.md (Chinese Simplified) --- .../current/nodes-and-miners/hosted-nodes.md | 25 +++++++++++++++++++ 1 file changed, 25 insertions(+) create mode 100644 i18n/zh/docusaurus-plugin-content-docs/current/nodes-and-miners/hosted-nodes.md diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/nodes-and-miners/hosted-nodes.md b/i18n/zh/docusaurus-plugin-content-docs/current/nodes-and-miners/hosted-nodes.md new file mode 100644 index 0000000000..12d86c7ee2 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/current/nodes-and-miners/hosted-nodes.md @@ -0,0 +1,25 @@ +--- +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. From 43776a9fabe874cebba93c99705e04ef672a15fc Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:45:37 +0100 Subject: [PATCH 0542/1444] New translations authentication.md (Vietnamese) --- .../current/stacks-academy/authentication.md | 63 +++++++++++++++++++ 1 file changed, 63 insertions(+) create mode 100644 i18n/vi/docusaurus-plugin-content-docs/current/stacks-academy/authentication.md diff --git a/i18n/vi/docusaurus-plugin-content-docs/current/stacks-academy/authentication.md b/i18n/vi/docusaurus-plugin-content-docs/current/stacks-academy/authentication.md new file mode 100644 index 0000000000..02296a19a3 --- /dev/null +++ b/i18n/vi/docusaurus-plugin-content-docs/current/stacks-academy/authentication.md @@ -0,0 +1,63 @@ +--- +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 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. From 1bd7e726b56f3945022c1a46e9389a30d9a7c09d Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:45:38 +0100 Subject: [PATCH 0543/1444] New translations bns.md (Vietnamese) --- .../current/stacks-academy/bns.md | 242 ++++++++++++++++++ 1 file changed, 242 insertions(+) create mode 100644 i18n/vi/docusaurus-plugin-content-docs/current/stacks-academy/bns.md diff --git a/i18n/vi/docusaurus-plugin-content-docs/current/stacks-academy/bns.md b/i18n/vi/docusaurus-plugin-content-docs/current/stacks-academy/bns.md new file mode 100644 index 0000000000..4c89d9e56c --- /dev/null +++ b/i18n/vi/docusaurus-plugin-content-docs/current/stacks-academy/bns.md @@ -0,0 +1,242 @@ +--- +title: Blockchain Naming System +description: Binds Stacks usernames to off-chain state +sidebar_position: 8 +--- + +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 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). From bf1dd240008bf182cdbba3e5ab3262e7252ed931 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:45:39 +0100 Subject: [PATCH 0544/1444] New translations docs.md (Vietnamese) --- .../current/contribute/docs.md | 24 ++++++++++++------- 1 file changed, 15 insertions(+), 9 deletions(-) diff --git a/i18n/vi/docusaurus-plugin-content-docs/current/contribute/docs.md b/i18n/vi/docusaurus-plugin-content-docs/current/contribute/docs.md index 77705451b8..b2fef628f9 100644 --- a/i18n/vi/docusaurus-plugin-content-docs/current/contribute/docs.md +++ b/i18n/vi/docusaurus-plugin-content-docs/current/contribute/docs.md @@ -7,7 +7,7 @@ description: Learn how this site is built, and how you can contribute to it. 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). +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/). @@ -15,7 +15,7 @@ Don't want to learn it? No need to. Write [in plain text an issue on Github](htt :::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 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). @@ -24,28 +24,32 @@ To add new content, they are two different ways to do it, the [easy way](#easy-w [**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. +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 yourhanges in real time. + - `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. -## Aditional information +## 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 ``` @@ -54,8 +58,8 @@ Before running this command for the first time you will need to run `npm install 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 ``` @@ -91,7 +95,7 @@ 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. +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 @@ -124,6 +128,7 @@ And execute prettier with the following command: npx prettier --write mynewfiletocheck.md ``` --> + ### 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. @@ -138,6 +143,7 @@ To write a code block, you need to wrap your code in ` ```language `, and end yo (define-public (get-counter) (ok (var-get counter))) ``` + ### Admonitions You can use the following admonitions to highlight content. @@ -204,4 +210,4 @@ Some **content** with _markdown_ `syntax`. Some **content** with _markdown_ `syntax`. -::: \ No newline at end of file +::: From 6da96c24c66f18c9f86acc2cc6f8643d4d3c1fef Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:45:41 +0100 Subject: [PATCH 0545/1444] New translations translations.md (Vietnamese) --- .../current/contribute/translations.md | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/i18n/vi/docusaurus-plugin-content-docs/current/contribute/translations.md b/i18n/vi/docusaurus-plugin-content-docs/current/contribute/translations.md index bd9a452333..fe8f8c6027 100644 --- a/i18n/vi/docusaurus-plugin-content-docs/current/contribute/translations.md +++ b/i18n/vi/docusaurus-plugin-content-docs/current/contribute/translations.md @@ -1,25 +1,24 @@ --- title: Contribute with translations -description: Want to help tranlating these docs to your local language? +description: Want to help translating 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. +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 Crodin intead. +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 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 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) From b3f630747b6b6390ac649615884b8f0b515a6333 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:45:43 +0100 Subject: [PATCH 0546/1444] New translations gaia-on-ec2.md (Vietnamese) --- .../current/gaia/gaia-on-ec2.md | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) 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 index 2067e7d57c..3f58ca5e68 100644 --- 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 @@ -26,9 +26,10 @@ Use a link in the table to launch the [CloudFormation](https://console.aws.amazo ### Step 2 - Setup stack using template -You need to configure the template with the appropiate values for your hub and domain it runs on. +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 ``` @@ -52,7 +53,7 @@ Specify the stack details and then click `Next`: ![Specify template](/img/cloudf | 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`. | +| 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 | @@ -93,7 +94,9 @@ ssh -i admin@ 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 +![](/img/cloudformation-gaia-template1-designer.png) From 717afa60e7b4e8b11fb1701b4ffaac16bb24db30 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:45:44 +0100 Subject: [PATCH 0547/1444] New translations gaia.md (Vietnamese) --- .../current/gaia/gaia.md | 12 +++++++++--- 1 file changed, 9 insertions(+), 3 deletions(-) diff --git a/i18n/vi/docusaurus-plugin-content-docs/current/gaia/gaia.md b/i18n/vi/docusaurus-plugin-content-docs/current/gaia/gaia.md index 1070857350..f86a0d61dc 100644 --- a/i18n/vi/docusaurus-plugin-content-docs/current/gaia/gaia.md +++ b/i18n/vi/docusaurus-plugin-content-docs/current/gaia/gaia.md @@ -1,14 +1,20 @@ --- title: Gaia description: Decentralized storage architecture for off-chain data -sidebar_position: 5 +sidebar_position: 6 tags: - gaia --- ## Introduction -Apps built with the Stacks blockchain store off-chain data using a storage system called Gaia. +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. @@ -38,7 +44,7 @@ The Stacks blockchain stores only identity data. Data created by the actions of 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) +![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. From 29248ee69a83e8afc8e7962a90ddc6a1d73bd590 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:45:45 +0100 Subject: [PATCH 0548/1444] New translations setup-linux.md (Vietnamese) --- .../current/gaia/setup-linux.md | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) 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 index db427f890a..2c0ca2b92e 100644 --- a/i18n/vi/docusaurus-plugin-content-docs/current/gaia/setup-linux.md +++ b/i18n/vi/docusaurus-plugin-content-docs/current/gaia/setup-linux.md @@ -1,6 +1,6 @@ --- 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. +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 @@ -19,8 +19,7 @@ This configuration will setup the following 4 docker containers: 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: +**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 @@ -48,8 +47,7 @@ chmod +x ${DESTINATION_DC}/docker-compose 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. +**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 From 4406cd3ecb42b9e7410b56d5519267ce76658594 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:45:46 +0100 Subject: [PATCH 0549/1444] New translations digitalocean.md (Vietnamese) --- .../current/nodes-and-miners/digitalocean.md | 41 +++++++++++-------- 1 file changed, 25 insertions(+), 16 deletions(-) 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 index dd7194f504..15df918d04 100644 --- 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 @@ -1,28 +1,30 @@ --- -title: Stacks on DigitalOcean +title: Run a Node with Digital Ocean description: A guide to setup Stacks on DigitalOcean -sidebar_position: 4 +sidebar_position: 2 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). +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`. +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 plan that meets the minimum requirements) and your prefered datacenter region. ![](/img/sh_digitalocean-choose-plan.png) +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 if your prefer. +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) @@ -46,41 +48,48 @@ Congratulations! You are now running the Stacks Blockchain. You can click on `Co ## 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). +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`. -Once the stacks blockchain starts to sync with peers, application ports will open and nginx port 80 will now start proxying requests. +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 v3.0.3 (master:cd0c8aef)", + "server_version": "stacks-blockchain-api v6.2.3 (master:77ab3ae2)", "status": "ready", "chain_tip": { - "block_height": 16220, - "block_hash": "0x3123fba9c0de6b569573494cf83c1d5d198a66bfd5f48ef97949b6bf11ba13be", - "index_block_hash": "0xeec960fbbd6186b4ccac85ce12adba72be497d881f81e077305c90955b51a6ae" + "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/README.md#quickstart). +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). -## API Creation +## 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 -curl -X POST -H 'Content-Type: application/json' \ +$ export TOKEN= +$ 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"}' \ + '{"name":"stacks-blockchain","region":"sfo2","size":"s-2vcpu-4gb","image":"stacksfoundation-stacksblockchain"}' \ "https://api.digitalocean.com/v2/droplets" ``` From 3c428ff672c7622444f1812b35f715b0a11b43b6 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:45:47 +0100 Subject: [PATCH 0550/1444] New translations index.md (Vietnamese) --- .../current/nodes-and-miners/index.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) 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 index b6cbb9754a..e5f4f2c250 100644 --- 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 @@ -1,11 +1,11 @@ --- title: Nodes and Miners description: Nodes and Miners -sidebar_position: 7 +sidebar_position: 5 --- -Here are all the steps to run nodes and miners, both on mainnet and testnet. +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. -## What's a Stacks node? +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. -## What's a Stacks miner? +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. From 1a9bd312d3dcf4070d01c09731714655698b1f31 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:45:48 +0100 Subject: [PATCH 0551/1444] New translations miner-mainnet.md (Vietnamese) --- .../current/nodes-and-miners/miner-mainnet.md | 301 +++++++----------- 1 file changed, 110 insertions(+), 191 deletions(-) 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 index 468a01df66..5afd34c23f 100644 --- 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 @@ -1,166 +1,100 @@ --- title: Mine mainnet Stacks tokens -description: Set up and run a miner on the Stacks 2.0 mainnet -sidebar_position: 5 +description: Set up and run a miner on Stacks Mainnet +sidebar_position: 6 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. +For more on the technical details of mining, please review the [mining guide](../stacks-academy/mining) -If you're interested in mining on the testnet, you can find instructions on how to do that [here](miner-testnet): +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 want to learn more about the technical details of mining, please review the [mining guide](../understand-stacks/mining): +If you're interested in mining on the Stacks testnet, you can find instructions on how to do that [here](miner-testnet): -## Running bitcoind locally +## Running a Bitcoin Mainnet Full Node -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) +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. -First, download the bitcoind software for your platform from https://bitcoin.org/en/download. +- [Ensure your computer meets the minimum hardware requirements before continuing.](https://bitcoin.org/en/bitcoin-core/features/requirements#system-requirements) -Next, start bitcoind with the following configuration: +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): -```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 -``` +:::tip It is recommened to use a persistent location for the chainstate, in the steps below we're using `/bitcoin` ::: -Finally, start bitcoind as follows: +### Update the Bitcoin Configuration File -```bash -bitcoind -conf=path/to/bitcoin.conf -``` - -It may take a few days for the node to synchronize with the Bitcoin mainnet. +Next, update the bitcoin configuration: -## 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: +- **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 -[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 = "" -... +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 ``` -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. +### Start Bitcoin -To run your miner, run this in the command line: +Finally, start bitcoin as follows (adjust the `conf` path to where it was created in the previous step, i.e. `$HOME/bitcoin.conf`): ```bash -stacks-node start --config=./testnet/stacks-node/conf/mainnet-miner-conf.toml +bitcoind -conf=$HOME/bitcoin.conf ``` -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 -``` +:::note +It will take a few days for the node to synchronize with Bitcoin mainnet. +::: -The above code will compile an optimized binary. To use it, run: +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 -cd ../.. -./target/release/stacks-node start --config=./mainnet-miner-conf.toml +$ bitcoin-cli \ + -rpcconnect=localhost \ + -rpcport=8332 \ + -rpcuser=btcuser \ + -rpcpassword=btcpassword \ +getblockchaininfo | jq .blocks +773281 ``` -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 Stacks Blockchain miner -## Running a miner in Windows +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) -### Prerequisites +_There may be some extra requirements to building, [defined here](https://github.com/stacksfoundation/miner-docs/blob/main/prerequisites.md#install-required-packages)_ -Make sure are [running a node](run-a-node) and [running bitcoind locally](#running-bitcoind-locally) before starting this tutorial. +:::tip It is recommened to use a persistent location for the chainstate, in the steps below we're using `/stacks-blockchain` ::: -### Generate keychain and get mainnet tokens in Windows +### Generate a keychain -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 cryptocurrency 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: +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 -npm install --global @stacks/cli -stx make_keychain > cli_keychain.json -type cli_keychain.json +npx @stacks/cli make_keychain 2>/dev/null | jq -r ``` -After this runs, you'll probably see some installation logs, and at the end you should see some JSON that looks like this: +After this runs, you should see some JSON printed to the screen that looks like this: ```json { @@ -174,109 +108,99 @@ After this runs, you'll probably see some installation logs, and at the end you } ``` -:::tip Check out the [Stacks CLI reference](https://docs.hiro.so/references/stacks-cli) for more details ::: +:::warning **Do not lose this information** - we'll need to use the `privateKey` and `btcAddress` fields in later steps. ::: -The above BTC address will then need to be imported into the BTC network. +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=your-user -rpcpassword=your-password importaddress +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 configuration file + + +### Update the Stacks Blockchain 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). +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`. -Update the following properties: +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] -... -# Enter your private key here -seed = "replace-with-your-private-key" -local_peer_seed = "replace-with-your-private-key" -... +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] -... -# To mine on mainnet, you need to run bitcoind locally -# Details can be found in above section, 'Running bitcoind locally' +chain = "bitcoin" +mode = "mainnet" peer_host = "127.0.0.1" -username = "" -password = "" -... +username = "" +password = "" +rpc_port = 8332 +peer_port = 8333 +satoshis_per_byte = 100 +burn_fee_cap = 20000 ``` -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 +### Start the Stacks Blockchain -To start your miner, run this in the command line: +To run your miner, run this in the command line: ```bash -stacks-node start --config=testnet/stacks-node/conf/mainnet-miner-conf.toml +stacks-node start --config=$HOME/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 +### 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 -set RUST_BACKTRACE=full; -set STACKS_LOG_DEBUG=1; -stacks-node start --config=mainnet-miner-conf.toml +STACKS_LOG_DEBUG=1 stacks-node start --config=$HOME/mainnet-miner-conf.toml ``` -## Optional: Running with Docker +--- + +## Optional: Running a Stacks Blockchain miner with Docker -Alternatively, you can run the mainnet node with Docker. +Alternatively, you can run a Stacks mainnet miner with Docker. -:::caution Ensure you have [Docker](https://docs.docker.com/get-docker/) installed on your machine. ::: +:::caution Ensure you have [Docker](https://docs.docker.com/get-docker/) installed. ::: -### Generate keychain and get tokens +### 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 +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 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: +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). -```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 = "" -... -``` +### Update Stacks Blockchain Docker Configuration File -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. +Use the steps oulined above to create the [configuration file](miner-mainnet#update-the-stacks-blockchain-configuration-file) -### Start the miner +### 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 ::: @@ -287,7 +211,8 @@ docker run -d \ --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" \ + -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 \ @@ -302,9 +227,9 @@ 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). +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 on your machine: +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) @@ -313,13 +238,7 @@ Ensure you have the following prerequisites installed on your machine: ### 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). +Use the steps [outlined above](miner-mainnet#generate-a-keychain-and-get-some-tokens) ### Install the chart and run the miner From 38be050d33383c016969c20ed7e941e2dd0d6f09 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:45:49 +0100 Subject: [PATCH 0552/1444] New translations miner-testnet.md (Vietnamese) --- .../current/nodes-and-miners/miner-testnet.md | 318 +++++++----------- 1 file changed, 130 insertions(+), 188 deletions(-) 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 index b572df3ba2..c0a27e63d5 100644 --- 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 @@ -1,35 +1,52 @@ --- title: Mine testnet Stacks tokens -description: Set up and run a miner on the Stacks 2.0 testnet -sidebar_position: 4 +description: Set up and run a miner on Stacks Testnet +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 testnet. +For more on the technical details of mining, please review the [mining guide](../stacks-academy/mining) -If you want to learn more about the technical details of mining, please review the [mining guide](../understand-stacks/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)). -## Running bitcoind locally +If you're interested in mining on the Stacks mainnet, you can find instructions on how to do that [here](miner-mainnet): -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) +## Running a Bitcoin Testnet Full Node -First, download the bitcoind software for your platform from https://bitcoin.org/en/download. +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. -Next, start bitcoind with the following configuration: +- [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 -rpcuser=your-bitcoind-username -rpcpassword=your-bitcoind-password testnet=1 -txindex=0 -listen=1 -rpcserialversion=0 -maxorphantx=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 @@ -37,126 +54,51 @@ 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" -... +### Start Bitcoin -[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: +Finally, start bitcoind as follows: ```bash -stacks-node start --config=./testnet/stacks-node/conf/testnet-miner-conf.toml +bitcoind -conf=$HOME/bitcoin.conf ``` -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 -``` +:::note +It will take a few hours for the node to synchronize with Bitcoin testnet. +::: -The above code will compile an optimized binary. To use it, run: +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 -cd ../.. -./target/release/stacks-node start --config=./testnet/conf/testnet-follower-conf.toml +$ bitcoin-cli \ + -rpcconnect=localhost \ + -rpcport=18332 \ + -rpcuser=btcuser \ + -rpcpassword=btcpass \ +getblockchaininfo | jq .blocks +2417570 ``` -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 +## Running a Stacks Blockchain miner -### Prerequisites +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) -Make sure are [running a testnet node](run-a-node) before starting this tutorial. +_There may be some extra requirements to building, [defined here](https://github.com/stacksfoundation/miner-docs/blob/main/prerequisites.md#install-required-packages)_ -### Generate keychain and get testnet tokens in Windows +:::tip It is recommened to use a persistent location for the chainstate, in the steps below we're using `/stacks-blockchain` ::: -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. +### Generate a keychain -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. +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. -Generate a keychain: +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 -npm install --global @stacks/cli -stx make_keychain -t > cli_keychain.json -type cli_keychain.json +npx @stacks/cli make_keychain -t 2>/dev/null | jq -r ``` -After this runs, you'll probably see some installation logs, and at the end you should see some JSON that looks like this: +After this runs, you should see some JSON printed to the screen that looks like this: ```json { @@ -170,107 +112,110 @@ After this runs, you'll probably see some installation logs, and at the end you } ``` -:::tip Check out the [Stacks CLI reference](https://docs.hiro.so/references/stacks-cli) for more details ::: +:::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. -Request BTC from faucet: +### Update the Stacks Blockchain Configuration File -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. 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`. -### Update configuration file +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. -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). +Next, update the bitcoin configuration: -Update the following properties: +- **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] -... -seed = "replace-with-your-private-key" -local_peer_seed = "replace-with-your-private-key" -... +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] -... -# To mine on Testnet, you need to run bitcoind locally -# Details can be found in above section, 'Running bitcoind locally' +chain = "bitcoin" +mode = "xenon" peer_host = "127.0.0.1" -username = "" -password = "" -... +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 ``` -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 +### Start the Stacks Blockchain -To start your miner, run this in the command line: +To run your miner, run this in the command line: ```bash -stacks-node start --config=testnet/stacks-node/conf/testnet-miner-conf.toml +stacks-node start --config=$HOME/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 +### 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 -set RUST_BACKTRACE=full; -set STACKS_LOG_DEBUG=1; -stacks-node start --config=testnet-miner-conf.toml +STACKS_LOG_DEBUG=1 stacks-node start --config=$HOME/testnet-miner-conf.toml ``` -## Optional: Running with Docker +--- + +## Optional: Running a Stacks Blockchain miner with Docker -Alternatively, you can run the testnet node with Docker. +Alternatively, you can run a Stacks testnet miner with Docker. -:::warning Ensure you have [Docker](https://docs.docker.com/get-docker/) installed on your machine. ::: +:::caution Ensure you have [Docker](https://docs.docker.com/get-docker/) installed ::: -### Generate keychain and get testnet tokens +### Generate a Keychain and Get Some Tokens Generate a keychain: ```bash -docker run -i node:14-alpine npx @stacks/cli make_keychain -t 2>/dev/null +docker run -i node:14-alpine npx @stacks/cli make_keychain 2>/dev/null | jq -r ``` -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 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. -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 Stacks Blockchain Docker Configuration File -Update the following properties: +Use the steps oulined above to create the [configuration file](miner-testnet#update-the-stacks-blockchain-configuration-file) -```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 +### 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 ::: @@ -281,7 +226,8 @@ docker run -d \ --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" \ + -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 \ @@ -294,26 +240,22 @@ You can review the node logs with this command: 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). +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 on your machine: +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 testnet tokens - -Generate a keychain: - -```bash -docker run -i node:14-alpine npx @stacks/cli make_keychain -t 2>/dev/null -``` +### Generate keychain and get some tokens -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. +Use the steps [outlined above](miner-testnet#generate-a-keychain-and-get-some-tokens) ### Install the chart and run the miner @@ -324,7 +266,7 @@ 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.node.seed="replace-with-your-privateKey-from-generate-keychain-step" \ ``` You can review the node logs with this command: From 2ded197a7e34ae6c5ee8e118c6dec043a96987b3 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:45:50 +0100 Subject: [PATCH 0553/1444] New translations stacks-node-configuration.md (Vietnamese) --- .../stacks-node-configuration.md | 158 +++++++++++------- 1 file changed, 101 insertions(+), 57 deletions(-) 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 index 89af343dc6..cd216e7103 100644 --- 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 @@ -1,7 +1,7 @@ --- title: Stacks Node Configuration description: Configuration parameters and options for the stacks-node binary -sidebar_position: 6 +sidebar_position: 4 --- ## Usage @@ -10,97 +10,141 @@ sidebar_position: 6 stacks-node sub-command [--subcommand-option ] ``` -## Subcommands +### 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 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 -### mocknet +## Configuration File Options -Start a node based on a fast local setup emulating a burnchain. Ideal for smart contract development. +The Stacks Blockchain configuration file has multiple sections under which an option may be placed. -Example: +- [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) -```bash -stacks-node mocknet -``` +For reference, several configuration file examples are [available here](https://github.com/stacks-network/stacks-blockchain/tree/master/testnet/stacks-node/conf) -### krypton +- [Example mainnet follower configuration](./stacks-node-configuration#example-mainnet-follower-configuration) -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). +### node -Example: +Contains various configuration options for the stacks-node binary. -```bash -stacks-node krypton -``` +| 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. | -### testnet +### events_observer -Start a node that will join and stream blocks from the public testnet. +:::info This section is _optional_ and not required -Example: +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. -```bash -stacks-node testnet -``` +| 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. | | -### mainnet +### connection_options -Start a node that joins and streams blocks from the public mainnet. +:::info This section is _optional_ and not required. -Example: +However, if this section is added, **all** fields are required ::: -```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. +Specifies configuration options for others connecting to the stacks node. -#### Arguments +| 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 | -**--config**: relative or absolute path to the TOML config file. Required. +### burnchain -Example: +This section contains configuration options pertaining to the blockchain the stacks-node binds to on the backend for proof-of-transfer (BTC). -```bash -stacks-node start --config=/path/to/config.toml -``` +| 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` | -See [Configuration File Options](#configuration-file-options) for more information. +#### Mining -#### version +| 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`. | -Displays information about the current version and the release cycle. +### ustx_balance -Example: +- `mocknet`/`testnet` only -```bash -stacks-node version -``` +This section contains configuration options allocating microSTX per address in the genesis block -#### help +This section can repeat multiple times, but each section can only define a single address. -Displays a help message. +:::info This section is only required for the `testnet` and `mocknet` networks. -Example: +However, if this section is added, **all** fields are required ::: -```bash -stacks-node help -``` +| 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 | -## Configuration File Options +## Example Mainnet Follower Configuration -The TOML configuration file has multiple sections under which an option may be placed. +```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" -To see a list of example configurations, [please see this page](https://github.com/stacks-network/stacks-blockchain/tree/master/testnet/stacks-node/conf). +[burnchain] +chain = "bitcoin" +mode = "mainnet" +peer_host = "localhost" +username = "user" +password = "pass" +rpc_port = 8332 +peer_port = 8333 -### Section: node +[[events_observer]] +endpoint = "localhost:3700" +retry_count = 255 +events_keys = ["*"] +``` -Contains various configuration options pertaining to the stacks-node. -Example: + From 4ae633922b177b22086ab798e0c68b7b05eeda1c Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:45:51 +0100 Subject: [PATCH 0554/1444] New translations accounts.md (Vietnamese) --- .../current/stacks-academy/accounts.md | 215 ++++++++++++++++++ 1 file changed, 215 insertions(+) create mode 100644 i18n/vi/docusaurus-plugin-content-docs/current/stacks-academy/accounts.md diff --git a/i18n/vi/docusaurus-plugin-content-docs/current/stacks-academy/accounts.md b/i18n/vi/docusaurus-plugin-content-docs/current/stacks-academy/accounts.md new file mode 100644 index 0000000000..55d0165def --- /dev/null +++ b/i18n/vi/docusaurus-plugin-content-docs/current/stacks-academy/accounts.md @@ -0,0 +1,215 @@ +--- +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" + } + } + ] +} +``` From 674cef7668ae358dde0eb102091c49962322940d Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:45:52 +0100 Subject: [PATCH 0555/1444] New translations microblocks.md (Vietnamese) --- .../current/stacks-academy/microblocks.md | 107 ++++++++++++++++++ 1 file changed, 107 insertions(+) create mode 100644 i18n/vi/docusaurus-plugin-content-docs/current/stacks-academy/microblocks.md diff --git a/i18n/vi/docusaurus-plugin-content-docs/current/stacks-academy/microblocks.md b/i18n/vi/docusaurus-plugin-content-docs/current/stacks-academy/microblocks.md new file mode 100644 index 0000000000..9310aa65be --- /dev/null +++ b/i18n/vi/docusaurus-plugin-content-docs/current/stacks-academy/microblocks.md @@ -0,0 +1,107 @@ +--- +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. + +[provides an endpoint]: https://docs.hiro.so/get-started/stacks-blockchain-api#nonce-handling +[microblocks_api]: https://docs.hiro.so/api#tag/Microblocks From 16b5b174b200aae96ef53ca40b18cf9f841aa2cc Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:45:53 +0100 Subject: [PATCH 0556/1444] New translations mining.md (Vietnamese) --- .../current/stacks-academy/mining.md | 84 +++++++++++++++++++ 1 file changed, 84 insertions(+) create mode 100644 i18n/vi/docusaurus-plugin-content-docs/current/stacks-academy/mining.md diff --git a/i18n/vi/docusaurus-plugin-content-docs/current/stacks-academy/mining.md b/i18n/vi/docusaurus-plugin-content-docs/current/stacks-academy/mining.md new file mode 100644 index 0000000000..e6e93e130a --- /dev/null +++ b/i18n/vi/docusaurus-plugin-content-docs/current/stacks-academy/mining.md @@ -0,0 +1,84 @@ +--- +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 From 469c8e33e3ac205f83aa9e6ce7e53cfc51dc6f82 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:45:53 +0100 Subject: [PATCH 0557/1444] New translations network.md (Vietnamese) --- .../current/stacks-academy/network.md | 148 ++++++++++++++++++ 1 file changed, 148 insertions(+) create mode 100644 i18n/vi/docusaurus-plugin-content-docs/current/stacks-academy/network.md diff --git a/i18n/vi/docusaurus-plugin-content-docs/current/stacks-academy/network.md b/i18n/vi/docusaurus-plugin-content-docs/current/stacks-academy/network.md new file mode 100644 index 0000000000..a0dc623d97 --- /dev/null +++ b/i18n/vi/docusaurus-plugin-content-docs/current/stacks-academy/network.md @@ -0,0 +1,148 @@ +--- +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 +} +``` From 28ffb6ec932aa76beed7c5a1ac192125c1e7dc34 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:45:54 +0100 Subject: [PATCH 0558/1444] New translations stacking.md (Vietnamese) --- .../current/stacks-academy/stacking.md | 151 ++++++++++++++++++ 1 file changed, 151 insertions(+) create mode 100644 i18n/vi/docusaurus-plugin-content-docs/current/stacks-academy/stacking.md diff --git a/i18n/vi/docusaurus-plugin-content-docs/current/stacks-academy/stacking.md b/i18n/vi/docusaurus-plugin-content-docs/current/stacks-academy/stacking.md new file mode 100644 index 0000000000..545f538ecb --- /dev/null +++ b/i18n/vi/docusaurus-plugin-content-docs/current/stacks-academy/stacking.md @@ -0,0 +1,151 @@ +--- +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. 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. + +![](/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 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 (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 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) From fa814bd916a7bf09333f8147eb0dc2f5265deb80 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:45:55 +0100 Subject: [PATCH 0559/1444] New translations technical-specs.md (Vietnamese) --- .../current/stacks-academy/technical-specs.md | 79 +++++++++++++++++++ 1 file changed, 79 insertions(+) create mode 100644 i18n/vi/docusaurus-plugin-content-docs/current/stacks-academy/technical-specs.md diff --git a/i18n/vi/docusaurus-plugin-content-docs/current/stacks-academy/technical-specs.md b/i18n/vi/docusaurus-plugin-content-docs/current/stacks-academy/technical-specs.md new file mode 100644 index 0000000000..695f849e1a --- /dev/null +++ b/i18n/vi/docusaurus-plugin-content-docs/current/stacks-academy/technical-specs.md @@ -0,0 +1,79 @@ +--- +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). +- 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 whitepaper v2](https://www.youtube.com/watch?v=Wd-Bfe8Sn-Y). From fa68c2016e5a778e49434c06a91c95387c79507e Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:45:56 +0100 Subject: [PATCH 0560/1444] New translations testnet.md (Vietnamese) --- .../current/stacks-academy/testnet.md | 35 +++++++++++++++++++ 1 file changed, 35 insertions(+) create mode 100644 i18n/vi/docusaurus-plugin-content-docs/current/stacks-academy/testnet.md diff --git a/i18n/vi/docusaurus-plugin-content-docs/current/stacks-academy/testnet.md b/i18n/vi/docusaurus-plugin-content-docs/current/stacks-academy/testnet.md new file mode 100644 index 0000000000..f8b9f03df2 --- /dev/null +++ b/i18n/vi/docusaurus-plugin-content-docs/current/stacks-academy/testnet.md @@ -0,0 +1,35 @@ +--- +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. + +### 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) From 1677932fa67a345fc1fee049cdfbb9895046a210 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:45:57 +0100 Subject: [PATCH 0561/1444] New translations transactions.md (Vietnamese) --- .../current/stacks-academy/transactions.md | 40 +++++++++++++++++++ 1 file changed, 40 insertions(+) create mode 100644 i18n/vi/docusaurus-plugin-content-docs/current/stacks-academy/transactions.md diff --git a/i18n/vi/docusaurus-plugin-content-docs/current/stacks-academy/transactions.md b/i18n/vi/docusaurus-plugin-content-docs/current/stacks-academy/transactions.md new file mode 100644 index 0000000000..ba6b18f0f7 --- /dev/null +++ b/i18n/vi/docusaurus-plugin-content-docs/current/stacks-academy/transactions.md @@ -0,0 +1,40 @@ +--- +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). ::: From 3efcb10daa6569221a5262d120122f4405087e7b Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:45:58 +0100 Subject: [PATCH 0562/1444] New translations language-functions.md (Vietnamese) --- .../current/clarity/language-functions.md | 2028 +++++++++++++++++ 1 file changed, 2028 insertions(+) create mode 100644 i18n/vi/docusaurus-plugin-content-docs/current/clarity/language-functions.md diff --git a/i18n/vi/docusaurus-plugin-content-docs/current/clarity/language-functions.md b/i18n/vi/docusaurus-plugin-content-docs/current/clarity/language-functions.md new file mode 100644 index 0000000000..32989bba8e --- /dev/null +++ b/i18n/vi/docusaurus-plugin-content-docs/current/clarity/language-functions.md @@ -0,0 +1,2028 @@ +--- +title: Functions +description: See a detailed list of all functions for the Clarity language. +sidebar_position: 3 +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: + +#### 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-existent\"))))) ;; 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-existent\") ;; 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-existent\" })) ;; 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-existent\" }))) ;; 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-existent\" }))) ;; 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 \"Stacks\" '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 successfully 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_ transferred from another principal, but rather minted. + +If a non-positive amount is provided to mint, this function returns `(err 1)`. Otherwise, on successfully 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_ transferred 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 successfully 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 successfully 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)) +``` From a6d2a7a52dbad486f5998f22e85088f688a977a3 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:45:59 +0100 Subject: [PATCH 0563/1444] New translations language-keywords.md (Vietnamese) --- .../current/clarity/language-keywords.md | 146 ++++++++++++++++++ 1 file changed, 146 insertions(+) create mode 100644 i18n/vi/docusaurus-plugin-content-docs/current/clarity/language-keywords.md diff --git a/i18n/vi/docusaurus-plugin-content-docs/current/clarity/language-keywords.md b/i18n/vi/docusaurus-plugin-content-docs/current/clarity/language-keywords.md new file mode 100644 index 0000000000..1aca5359c3 --- /dev/null +++ b/i18n/vi/docusaurus-plugin-content-docs/current/clarity/language-keywords.md @@ -0,0 +1,146 @@ +--- +title: Keywords +description: See a detailed list of all keywords for the Clarity language. +sidebar_position: 4 +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 +``` From 85dd176f3cb7d4f5b1b4631816dc23ce246d68f7 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:46:00 +0100 Subject: [PATCH 0564/1444] New translations language-types.md (Vietnamese) --- .../current/clarity/language-types.md | 25 +++++++++++++++++++ 1 file changed, 25 insertions(+) create mode 100644 i18n/vi/docusaurus-plugin-content-docs/current/clarity/language-types.md diff --git a/i18n/vi/docusaurus-plugin-content-docs/current/clarity/language-types.md b/i18n/vi/docusaurus-plugin-content-docs/current/clarity/language-types.md new file mode 100644 index 0000000000..0af4577dc9 --- /dev/null +++ b/i18n/vi/docusaurus-plugin-content-docs/current/clarity/language-types.md @@ -0,0 +1,25 @@ +--- +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. | From 26ecad63029c8ffdd2c836567fef984b69d73de4 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:46:02 +0100 Subject: [PATCH 0565/1444] New translations miner-costs-and-fees.md (Vietnamese) --- .../current/nodes-and-miners/miner-costs-and-fees.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) 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 index 40397a51e0..dd8ee721cc 100644 --- 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 @@ -8,7 +8,7 @@ sidebar_position: 8 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 @@ -22,3 +22,5 @@ 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). From 00674a9c3d4e6d2af29b954369a2bcfa7743c0ba Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:46:03 +0100 Subject: [PATCH 0566/1444] New translations verify-miner.md (Vietnamese) --- .../current/nodes-and-miners/verify-miner.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) 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 index 094e3f03a1..18e8dd3a48 100644 --- 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 @@ -7,7 +7,7 @@ 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 +$ 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 -``` \ No newline at end of file +``` From c445a6f3752e426c6911bee1c357be59cbe11d74 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:46:04 +0100 Subject: [PATCH 0567/1444] New translations stacks-blockchain-api.md (Vietnamese) --- .../stacks-academy/stacks-blockchain-api.md | 41 +++++++++++++++++++ 1 file changed, 41 insertions(+) create mode 100644 i18n/vi/docusaurus-plugin-content-docs/current/stacks-academy/stacks-blockchain-api.md diff --git a/i18n/vi/docusaurus-plugin-content-docs/current/stacks-academy/stacks-blockchain-api.md b/i18n/vi/docusaurus-plugin-content-docs/current/stacks-academy/stacks-blockchain-api.md new file mode 100644 index 0000000000..ad9bb1822e --- /dev/null +++ b/i18n/vi/docusaurus-plugin-content-docs/current/stacks-academy/stacks-blockchain-api.md @@ -0,0 +1,41 @@ +--- +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`. ::: From b904bd13acc580ab71be170233161c9c6fe14d02 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:46:04 +0100 Subject: [PATCH 0568/1444] New translations run-a-node.md (Vietnamese) --- .../current/nodes-and-miners/run-a-node.md | 329 +++--------------- 1 file changed, 42 insertions(+), 287 deletions(-) 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 index 94d938c5ca..2993568ce4 100644 --- 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 @@ -1,5 +1,5 @@ --- -title: Run a node +title: Run a Node with Docker description: Set up and run a Stacks node sidebar_position: 1 tags: @@ -8,344 +8,99 @@ tags: ## Stacks Blockchain with Docker -Run your own Stacks Blockchain node easily with just few commands. +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) -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](./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) -## **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 -``` +## **Requirements:** -- With optional proxy: +The **minimum viable requirements** are listed below. -```bash -./manage.sh -n -a start -f proxy -``` +While you _can_ run a node using these specs, it's _recommended_ to assign more than the minimum for better performance. -- With optional bitcoin node: +- ⚠️ [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_ ) -```bash -./manage.sh -n -a start -f bitcoin -``` +:::caution MacOS with an ARM processor is NOT recommended -5. **Stop the Services** +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. ::: -```bash -./manage.sh -n -a stop -``` - -6. **Retrieve Service Logs** - -```bash -./manage.sh -n -a logs -``` - -- Export docker log files to `./exported-logs`: +## **Quickstart** -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. +The `` placeholder used below can be replaced with one of: -```bash -./manage.sh -n -a logs export -``` +- mainnet +- testnet +- mocknet -7. **Restart all services** +1. **Clone the stacks-blockchain-docker repository locally** ```bash -./manage.sh -n -a restart +git clone https://github.com/stacks-network/stacks-blockchain-docker && cd stacks-blockchain-docker ``` -- With optional proxy: +2. **Start the Services** ```bash -./manage.sh -n -a restart -f proxy +./manage.sh -n -a start ``` -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. +:::note With an optional HTTP proxy on port 80: ```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. - +./manage.sh -n -a start -f proxy ``` -9. **Download BNS data to** `./persistent-data/bns-data` - -```bash -./manage.sh bns -``` +::: -10. **Export stacks-blockchain-api events** (_Not applicable for mocknet_) +## **Accessing the services** -```bash -./manage.sh -n -a export -# check logs for completion -./manage.sh -n -a restart -``` +:::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. -11. **Replay stacks-blockchain-api events** (_Not applicable for mocknet_) +Follow the logs to track the sync progress: ```bash -./manage.sh -n -a import -# check logs for completion -./manage.sh -n -a restart +./manage.sh -n -a logs ``` -## **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` +- Ports `20443-20444` are exposed on `localhost` ```bash -curl -sL localhost:20443/v2/info | jq +curl -sL localhost:20443/v2/info | jq -r ``` **stacks-blockchain-api**: -- Port `3999` are exposed to `localhost` +- Port `3999` is exposed on `localhost` ```bash -curl -sL localhost:3999/v2/info | jq +curl -sL localhost:3999 | jq -r ``` **proxy**: -- Port `80` is exposed to `localhost` +- Port `80` is exposed on `localhost` ```bash -curl -sL localhost/v2/info | jq -curl -sL localhost/ | jq +curl -sL localhost/v2/info | jq -r +curl -sL localhost | jq -r ``` --- ## 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 -``` +:::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): ::: --- - -## **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 From ed9083008a7628797350993e0b72d0b577a3ecf6 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:46:05 +0100 Subject: [PATCH 0569/1444] New translations index.md (Vietnamese) --- .../current/clarity/index.md | 58 +++++++++++++++++++ 1 file changed, 58 insertions(+) create mode 100644 i18n/vi/docusaurus-plugin-content-docs/current/clarity/index.md diff --git a/i18n/vi/docusaurus-plugin-content-docs/current/clarity/index.md b/i18n/vi/docusaurus-plugin-content-docs/current/clarity/index.md new file mode 100644 index 0000000000..903de93a45 --- /dev/null +++ b/i18n/vi/docusaurus-plugin-content-docs/current/clarity/index.md @@ -0,0 +1,58 @@ +--- +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?2 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. If you are unsure what this means, let it not worry you for now. The serious advantage of decidability will become more apparent over time. + +### 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. From 06d0c850cda4b87749df7b2faaf78db82189aa06 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:46:06 +0100 Subject: [PATCH 0570/1444] New translations index.md (Vietnamese) --- .../current/stacks-academy/index.md | 11 +++++++++++ 1 file changed, 11 insertions(+) create mode 100644 i18n/vi/docusaurus-plugin-content-docs/current/stacks-academy/index.md diff --git a/i18n/vi/docusaurus-plugin-content-docs/current/stacks-academy/index.md b/i18n/vi/docusaurus-plugin-content-docs/current/stacks-academy/index.md new file mode 100644 index 0000000000..a5bdb3c790 --- /dev/null +++ b/i18n/vi/docusaurus-plugin-content-docs/current/stacks-academy/index.md @@ -0,0 +1,11 @@ +--- +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. From bbff61fe0e21ba6e63606899408f73e035968e28 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:46:07 +0100 Subject: [PATCH 0571/1444] New translations proof-of-transfer.md (Vietnamese) --- .../stacks-academy/proof-of-transfer.md | 83 +++++++++++++++++++ 1 file changed, 83 insertions(+) create mode 100644 i18n/vi/docusaurus-plugin-content-docs/current/stacks-academy/proof-of-transfer.md diff --git a/i18n/vi/docusaurus-plugin-content-docs/current/stacks-academy/proof-of-transfer.md b/i18n/vi/docusaurus-plugin-content-docs/current/stacks-academy/proof-of-transfer.md new file mode 100644 index 0000000000..50f4b739d6 --- /dev/null +++ b/i18n/vi/docusaurus-plugin-content-docs/current/stacks-academy/proof-of-transfer.md @@ -0,0 +1,83 @@ +--- +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. From fe61025be2b5ef3d59b0921725e1449977169765 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:46:08 +0100 Subject: [PATCH 0572/1444] New translations what-is-stacks.md (Vietnamese) --- .../current/stacks-academy/what-is-stacks.md | 102 ++++++++++++++++++ 1 file changed, 102 insertions(+) create mode 100644 i18n/vi/docusaurus-plugin-content-docs/current/stacks-academy/what-is-stacks.md diff --git a/i18n/vi/docusaurus-plugin-content-docs/current/stacks-academy/what-is-stacks.md b/i18n/vi/docusaurus-plugin-content-docs/current/stacks-academy/what-is-stacks.md new file mode 100644 index 0000000000..94277da8a9 --- /dev/null +++ b/i18n/vi/docusaurus-plugin-content-docs/current/stacks-academy/what-is-stacks.md @@ -0,0 +1,102 @@ +--- +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. + +There's a lot of jargon, possible assumptions, controversy, and cool technology wrapped up in those statements. So let's get started by getting a 30,000 foot view of what exactly Stacks is. + +## Stacks Explained in (Slightly Less Than) 10 Minutes + +
+ +
+ +## 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, Stacks takes a different approach. + +## 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). + +By taking this 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 with some unique properties, like having its own token, that allow it to maintain a historical ledger of all of its transactions and operate with its own security budget. + +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_. + +Nope. 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. From 632796ba05f1c6fb2457d11c87809fa7a4340ad0 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:46:09 +0100 Subject: [PATCH 0573/1444] New translations community-tutorials.md (Vietnamese) --- .../current/tutorials/community-tutorials.md | 24 +++++++++++++++++++ 1 file changed, 24 insertions(+) create mode 100644 i18n/vi/docusaurus-plugin-content-docs/current/tutorials/community-tutorials.md diff --git a/i18n/vi/docusaurus-plugin-content-docs/current/tutorials/community-tutorials.md b/i18n/vi/docusaurus-plugin-content-docs/current/tutorials/community-tutorials.md new file mode 100644 index 0000000000..a4f3d970ca --- /dev/null +++ b/i18n/vi/docusaurus-plugin-content-docs/current/tutorials/community-tutorials.md @@ -0,0 +1,24 @@ +--- +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/) From 2715cab5a073d8e635355ac53f22024129a7e639 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:46:10 +0100 Subject: [PATCH 0574/1444] New translations hello-stacks.md (Vietnamese) --- .../current/tutorials/hello-stacks.md | 759 ++++++++++++++++++ 1 file changed, 759 insertions(+) create mode 100644 i18n/vi/docusaurus-plugin-content-docs/current/tutorials/hello-stacks.md diff --git a/i18n/vi/docusaurus-plugin-content-docs/current/tutorials/hello-stacks.md b/i18n/vi/docusaurus-plugin-content-docs/current/tutorials/hello-stacks.md new file mode 100644 index 0000000000..a0a442d135 --- /dev/null +++ b/i18n/vi/docusaurus-plugin-content-docs/current/tutorials/hello-stacks.md @@ -0,0 +1,759 @@ +--- +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. From effcd0c9e3dac653b592d8789ecaf76780e75ef0 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:46:10 +0100 Subject: [PATCH 0575/1444] New translations index.md (Vietnamese) --- .../current/tutorials/index.md | 11 +++++++++++ 1 file changed, 11 insertions(+) create mode 100644 i18n/vi/docusaurus-plugin-content-docs/current/tutorials/index.md diff --git a/i18n/vi/docusaurus-plugin-content-docs/current/tutorials/index.md b/i18n/vi/docusaurus-plugin-content-docs/current/tutorials/index.md new file mode 100644 index 0000000000..1d544c7bc1 --- /dev/null +++ b/i18n/vi/docusaurus-plugin-content-docs/current/tutorials/index.md @@ -0,0 +1,11 @@ +--- +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. From 2614fca54d03f6109551d2f02c2eff31fb3140fe Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:46:11 +0100 Subject: [PATCH 0576/1444] New translations satoshis-ridge.md (Vietnamese) --- .../current/tutorials/satoshis-ridge.md | 75 +++++++++++++++++++ 1 file changed, 75 insertions(+) create mode 100644 i18n/vi/docusaurus-plugin-content-docs/current/tutorials/satoshis-ridge.md diff --git a/i18n/vi/docusaurus-plugin-content-docs/current/tutorials/satoshis-ridge.md b/i18n/vi/docusaurus-plugin-content-docs/current/tutorials/satoshis-ridge.md new file mode 100644 index 0000000000..596339ae74 --- /dev/null +++ b/i18n/vi/docusaurus-plugin-content-docs/current/tutorials/satoshis-ridge.md @@ -0,0 +1,75 @@ +--- +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 arguable one of its strengths. + +Instead, we need to create separate layers that add additional functionality without modify 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. From 12d4a8570b8d47c04d76c97a870cbb8242836139 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:46:12 +0100 Subject: [PATCH 0577/1444] New translations crash-course.md (Vietnamese) --- .../current/clarity/crash-course.md | 122 ++++++++++++++++++ 1 file changed, 122 insertions(+) create mode 100644 i18n/vi/docusaurus-plugin-content-docs/current/clarity/crash-course.md diff --git a/i18n/vi/docusaurus-plugin-content-docs/current/clarity/crash-course.md b/i18n/vi/docusaurus-plugin-content-docs/current/clarity/crash-course.md new file mode 100644 index 0000000000..5b27a3c275 --- /dev/null +++ b/i18n/vi/docusaurus-plugin-content-docs/current/clarity/crash-course.md @@ -0,0 +1,122 @@ +--- +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.md). + +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. + +```clojure +(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: + +```clojure +(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. From 5902eee083fb922f8765c88059333b8e6d4447e6 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:46:13 +0100 Subject: [PATCH 0578/1444] New translations sample-contracts.md (Vietnamese) --- .../current/clarity/sample-contracts.md | 14 ++++++++++++++ 1 file changed, 14 insertions(+) create mode 100644 i18n/vi/docusaurus-plugin-content-docs/current/clarity/sample-contracts.md diff --git a/i18n/vi/docusaurus-plugin-content-docs/current/clarity/sample-contracts.md b/i18n/vi/docusaurus-plugin-content-docs/current/clarity/sample-contracts.md new file mode 100644 index 0000000000..adb12a58fd --- /dev/null +++ b/i18n/vi/docusaurus-plugin-content-docs/current/clarity/sample-contracts.md @@ -0,0 +1,14 @@ +--- +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) From 6aa53a2ec78c963bbb99cf703f03c86627b151aa Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:46:14 +0100 Subject: [PATCH 0579/1444] New translations index.md (Vietnamese) --- .../current/cookbook/index.md | 64 +++++++++++++++++++ 1 file changed, 64 insertions(+) create mode 100644 i18n/vi/docusaurus-plugin-content-docs/current/cookbook/index.md diff --git a/i18n/vi/docusaurus-plugin-content-docs/current/cookbook/index.md b/i18n/vi/docusaurus-plugin-content-docs/current/cookbook/index.md new file mode 100644 index 0000000000..a2b0e42eea --- /dev/null +++ b/i18n/vi/docusaurus-plugin-content-docs/current/cookbook/index.md @@ -0,0 +1,64 @@ +--- +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 + +Swapping between Bitcoin and Stacks addresses + +Swapping between xBTC and BTC + +Verifying a transaction on the BTC chain + +## 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 + +Airdropping an NFT to a Bitcoin address + +## Stacking and Mining + +Simple stacking pool + +Continuous stacking + +Simple mining pool + +Proof of PoX payout + +## Oracles + +Creating a simple BTC price oracle + +## Frontend + +[Post conditions with Stacks.js](./post-conditions) + +[Authentication with Stacks.js](./stacks-js-auth) + +[Sending transactions with Stacks.js](./stacks-js-sending-transactions) + +## Complete Apps + +[Sup](https://github.com/kenrogers/sup) + +[Hello Stacks](https://github.com/kenrogers/hello-stacks) From 11fae98464bb54ad3ec7ac2ab65502a818a151ee Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:46:15 +0100 Subject: [PATCH 0580/1444] New translations btc-connection.md (Vietnamese) --- .../current/stacks-academy/btc-connection.md | 196 ++++++++++++++++++ 1 file changed, 196 insertions(+) create mode 100644 i18n/vi/docusaurus-plugin-content-docs/current/stacks-academy/btc-connection.md diff --git a/i18n/vi/docusaurus-plugin-content-docs/current/stacks-academy/btc-connection.md b/i18n/vi/docusaurus-plugin-content-docs/current/stacks-academy/btc-connection.md new file mode 100644 index 0000000000..b4db915969 --- /dev/null +++ b/i18n/vi/docusaurus-plugin-content-docs/current/stacks-academy/btc-connection.md @@ -0,0 +1,196 @@ +--- +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. + +## Stacks Among Other Bitcoin Layers + +In the [last section](./what-is-stacks.md) we covered what Stacks actually is and what problem it is solving, but this is not a new problem. The Bitcoin write problem has been a bit of a holy grail problem in the crypto world for a while now. + +Bitcoin is the OG cryptocurrency and has the largest market cap, but it also some of the least functionality, which means if we want to make it a productive asset and use it to build a decentralized economy, we need to take a layered approach and let Bitcoin do what it does best, while creating additional layers on top of it to add functionality. + +So how does Stacks compare to some of the other approaches to layering on top of Bitcoin? + +### 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. + +## 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. + +But because it has its own execution environment and smart contract state to maintain, it needs a token to incentivize maintenance of the network. + +But it goes further than that. It is possible to build a system like this without a token using something like merge-mining or a sidechain, but then we lose out on the additional benefit of having the chain state's safety underpinned by its entire token economy's value. + +In the case of Stacks, the safety and liveness of the chain are underpinned by this value, and the stacking mechanism incentivizes network members to increase this value. + +From Jude Nelson, Stacks core developer: + +"How hard is it to cause a safety failure (i.e. a double-spend via a reorg) on just the canonical Stacks chain fork? Anyone can become a miner by spending BTC, so without loss of generality, reverting the last block on the canonical chain is at least as hard in expectation as spending more BTC than the rest of the miners combined for that block. Because each Bitcoin block selects at most one Stacks block, the act of reorging the canonical Stacks chain back N blocks is the act of winning at least N + 1 blocks built off of a common ancestor that is N blocks deep. This is a lower bound on the number of Bitcoin blocks mined during which a reorg needs to take place — in practice, honest miners will keep working on the canonical chain, and will win some Stacks blocks of their own, which in turn increases the number of Stacks blocks the reorging miners must win. + +How costly is it to carry out a reorg of N blocks? It’s a function of how valuable STX is relative to BTC — the more valuable STX are, the more BTC honest miners are committing to mining (this has borne out in practice), and thus the more BTC a reorging miner must commit. Therefore, the cost of a reorg is a function of the value of STX. + +This is similar to the economic security of a PoW blockchain. Like in PoW, each fork of the Stacks chain has its own independent “security budget” — an attacker must out-spend the security budget to carry out a reorg, and the security budget is a function of the block rewards. In PoX, the only difference is that the miners spend another blockchain’s tokens (BTC in Stacks’ case) instead of energy. Therefore, Stacks can’t be a sidechain, a drivechain, or a merge-mined chain, because none of these other systems’ security budgets are a function of their tokens’ worth. Sidechains, drivechains, and merged-mined chains all rely on external miners for their safety, since their safety is guaranteed in part by external miners validating their blocks. The onus on these systems is to get external miners to care enough to do so, and in the case of sidechains, drivechains, and blind merged-mined chains, there is an additional onus to encourage their nodes to mine blocks at all (since there is no on-chain reward for them to earn by doing so). By contrast, disinterested Bitcoin miners neither assist nor prevent a reorg in PoX — they only record the history of all Stacks forks. + +PoX offers two additional, unique security properties on top of PoW. First, no matter how much BTC a reorging miner can commit, the act of executing a reorg is going to be time-consuming. Unless the attacker can attack the Bitcoin chain itself by quickly producing a better Bitcoin fork, a reorging miner must sustain the attack for at least N + 1 Bitcoin blocks. This gives honest miners and users ample time to notice and react to the reorg attempt. + +Second, the history of block production in all Stacks forks is embedded within Bitcoin. This allows the system to leverage Bitcoin’s security budget in order to ensure that all forks are public. This is because the act of producing a hidden Stacks fork, where the fork’s block hashes are not known to the honest miners, is the act of producing a hidden canonical Bitcoin fork. Therefore, the act of producing a hidden Stacks fork is at least as hard as reorging the Bitcoin chain. A PoX chain leverages this property not to prevent reorgs, but to make reorgs unprofitable. + +By anchoring blocks to an existing blockchain, a PoX chain forces reorgs to happen out in the open, thereby giving advance warning to all honest network participants when they happen. Honest miners, users, and exchanges will see the PoX transactions for reorg attempts on the existing blockchain, and adapt their behaviors accordingly: honest miners will increase their commitments, and users and exchanges will require more confirmations for transactions. This makes the act of carrying out a reorg while also making a profit much more challenging, since malicious reorgs — like selfish mining and double-spending — rely on secrecy to work effectively. Specific to Stacks, miners are additionally required to mine for a “warm-up” period of two blocks, during which they must spend BTC at their target commit levels but will not win any Stacks blocks. So, a high-budget reorg attempt will not only be costly, but will also alert the rest of the network before the damage is done." + +- [What Kind of Blockchain is Stacks?](https://stacks.org/stacks-blockchain) + +## 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) From 0c4874347591c83a0bbce56cbb0f38edc26182c0 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:46:16 +0100 Subject: [PATCH 0581/1444] New translations post-conditions.md (Vietnamese) --- .../current/stacks-academy/post-conditions.md | 39 +++++++++++++++++++ 1 file changed, 39 insertions(+) create mode 100644 i18n/vi/docusaurus-plugin-content-docs/current/stacks-academy/post-conditions.md diff --git a/i18n/vi/docusaurus-plugin-content-docs/current/stacks-academy/post-conditions.md b/i18n/vi/docusaurus-plugin-content-docs/current/stacks-academy/post-conditions.md new file mode 100644 index 0000000000..bb0727194f --- /dev/null +++ b/i18n/vi/docusaurus-plugin-content-docs/current/stacks-academy/post-conditions.md @@ -0,0 +1,39 @@ +--- +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). From 35749c746f99ac2d5ef35c6daabc20332ebe96de Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:46:16 +0100 Subject: [PATCH 0582/1444] New translations creating-an-ft.md (Vietnamese) --- .../current/cookbook/creating-an-ft.md | 99 +++++++++++++++++++ 1 file changed, 99 insertions(+) create mode 100644 i18n/vi/docusaurus-plugin-content-docs/current/cookbook/creating-an-ft.md diff --git a/i18n/vi/docusaurus-plugin-content-docs/current/cookbook/creating-an-ft.md b/i18n/vi/docusaurus-plugin-content-docs/current/cookbook/creating-an-ft.md new file mode 100644 index 0000000000..4e3bad99d2 --- /dev/null +++ b/i18n/vi/docusaurus-plugin-content-docs/current/cookbook/creating-an-ft.md @@ -0,0 +1,99 @@ +--- +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) + ) +) +``` From b4dade349a8581208bdb6931226c1164d9c42d3e Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:46:17 +0100 Subject: [PATCH 0583/1444] New translations creating-an-nft.md (Vietnamese) --- .../current/cookbook/creating-an-nft.md | 87 +++++++++++++++++++ 1 file changed, 87 insertions(+) create mode 100644 i18n/vi/docusaurus-plugin-content-docs/current/cookbook/creating-an-nft.md diff --git a/i18n/vi/docusaurus-plugin-content-docs/current/cookbook/creating-an-nft.md b/i18n/vi/docusaurus-plugin-content-docs/current/cookbook/creating-an-nft.md new file mode 100644 index 0000000000..08faf9393a --- /dev/null +++ b/i18n/vi/docusaurus-plugin-content-docs/current/cookbook/creating-an-nft.md @@ -0,0 +1,87 @@ +--- +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 +Code for this recipe has been pulled from [this NFT tutorial](https://blog.developerdao.com/building-an-nft-with-stacks-and-clarity) from Developer DAO. +::: + +## 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) + ) +) +``` From 68cc0f5cb3b4b86384145790ceb03c3fdf60b9ba Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:46:18 +0100 Subject: [PATCH 0584/1444] New translations post-conditions.md (Vietnamese) --- .../current/cookbook/post-conditions.md | 136 ++++++++++++++++++ 1 file changed, 136 insertions(+) create mode 100644 i18n/vi/docusaurus-plugin-content-docs/current/cookbook/post-conditions.md diff --git a/i18n/vi/docusaurus-plugin-content-docs/current/cookbook/post-conditions.md b/i18n/vi/docusaurus-plugin-content-docs/current/cookbook/post-conditions.md new file mode 100644 index 0000000000..571fc20d48 --- /dev/null +++ b/i18n/vi/docusaurus-plugin-content-docs/current/cookbook/post-conditions.md @@ -0,0 +1,136 @@ +--- +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. From 41f9eb45bcd105d79f5d753eba662a10c18863f7 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:46:19 +0100 Subject: [PATCH 0585/1444] New translations stacks-js-auth.md (Vietnamese) --- .../current/cookbook/stacks-js-auth.md | 98 +++++++++++++++++++ 1 file changed, 98 insertions(+) create mode 100644 i18n/vi/docusaurus-plugin-content-docs/current/cookbook/stacks-js-auth.md diff --git a/i18n/vi/docusaurus-plugin-content-docs/current/cookbook/stacks-js-auth.md b/i18n/vi/docusaurus-plugin-content-docs/current/cookbook/stacks-js-auth.md new file mode 100644 index 0000000000..89d1f06e00 --- /dev/null +++ b/i18n/vi/docusaurus-plugin-content-docs/current/cookbook/stacks-js-auth.md @@ -0,0 +1,98 @@ +--- +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 && ( + + ); +} +``` From 29422ab600a47faa66bfa905832eab5d83eb8eec Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:46:20 +0100 Subject: [PATCH 0586/1444] New translations stacks-js-sending-transactions.md (Vietnamese) --- .../stacks-js-sending-transactions.md | 55 +++++++++++++++++++ 1 file changed, 55 insertions(+) create mode 100644 i18n/vi/docusaurus-plugin-content-docs/current/cookbook/stacks-js-sending-transactions.md diff --git a/i18n/vi/docusaurus-plugin-content-docs/current/cookbook/stacks-js-sending-transactions.md b/i18n/vi/docusaurus-plugin-content-docs/current/cookbook/stacks-js-sending-transactions.md new file mode 100644 index 0000000000..849c7d1f42 --- /dev/null +++ b/i18n/vi/docusaurus-plugin-content-docs/current/cookbook/stacks-js-sending-transactions.md @@ -0,0 +1,55 @@ +--- +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. From 2afbd5f1b0cbfe43412c17d49ac6db2292219363 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:46:21 +0100 Subject: [PATCH 0587/1444] New translations _category_.json (Vietnamese) --- .../current/clarity/noteworthy-contracts/_category_.json | 8 ++++++++ 1 file changed, 8 insertions(+) create mode 100644 i18n/vi/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/_category_.json diff --git a/i18n/vi/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/_category_.json b/i18n/vi/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/_category_.json new file mode 100644 index 0000000000..f5de305558 --- /dev/null +++ b/i18n/vi/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/_category_.json @@ -0,0 +1,8 @@ +{ + "label": "Noteworthy Contracts", + "position": 4, + "link": { + "type": "generated-index", + "description": "Specific deployed Clarity Contracts worth mentioning." + } +} \ No newline at end of file From 8bf400197b6c7bafcb1c294a3525728210c8ce62 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:46:22 +0100 Subject: [PATCH 0588/1444] New translations bns-contract.md (Vietnamese) --- .../noteworthy-contracts/bns-contract.md | 519 ++++++++++++++++++ 1 file changed, 519 insertions(+) create mode 100644 i18n/vi/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/bns-contract.md diff --git a/i18n/vi/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/bns-contract.md b/i18n/vi/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/bns-contract.md new file mode 100644 index 0000000000..a7770b7d24 --- /dev/null +++ b/i18n/vi/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/bns-contract.md @@ -0,0 +1,519 @@ +--- +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 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` From d060586de5e32b5a583ff58a88ef57cd2bd916ce Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:46:22 +0100 Subject: [PATCH 0589/1444] New translations xbtc.md (Vietnamese) --- .../clarity/noteworthy-contracts/xbtc.md | 28 +++++++++++++++++++ 1 file changed, 28 insertions(+) create mode 100644 i18n/vi/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/xbtc.md diff --git a/i18n/vi/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/xbtc.md b/i18n/vi/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/xbtc.md new file mode 100644 index 0000000000..e535dcf260 --- /dev/null +++ b/i18n/vi/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/xbtc.md @@ -0,0 +1,28 @@ +--- +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) From d539d92f17358d559e86a118bcbd8c9973099049 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:46:23 +0100 Subject: [PATCH 0590/1444] New translations index.md (Vietnamese) --- .../current/glossary/index.md | 284 ++++++++++++++++++ 1 file changed, 284 insertions(+) create mode 100644 i18n/vi/docusaurus-plugin-content-docs/current/glossary/index.md diff --git a/i18n/vi/docusaurus-plugin-content-docs/current/glossary/index.md b/i18n/vi/docusaurus-plugin-content-docs/current/glossary/index.md new file mode 100644 index 0000000000..419c0e0d73 --- /dev/null +++ b/i18n/vi/docusaurus-plugin-content-docs/current/glossary/index.md @@ -0,0 +1,284 @@ +--- +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. From 2777d722be0ef05523fb02a749fb78937047b12f Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:46:24 +0100 Subject: [PATCH 0591/1444] New translations quicknode.md (Vietnamese) --- .../current/nodes-and-miners/quicknode.md | 45 +++++++++++++++++++ 1 file changed, 45 insertions(+) create mode 100644 i18n/vi/docusaurus-plugin-content-docs/current/nodes-and-miners/quicknode.md diff --git a/i18n/vi/docusaurus-plugin-content-docs/current/nodes-and-miners/quicknode.md b/i18n/vi/docusaurus-plugin-content-docs/current/nodes-and-miners/quicknode.md new file mode 100644 index 0000000000..1281964689 --- /dev/null +++ b/i18n/vi/docusaurus-plugin-content-docs/current/nodes-and-miners/quicknode.md @@ -0,0 +1,45 @@ +--- +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. From e51be2b1183d438b58a9f61e94d1d86c7452b11c Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:46:25 +0100 Subject: [PATCH 0592/1444] New translations defi.md (Vietnamese) --- .../current/services-using-stacks/defi.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) 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 index 51defacba7..58717a3234 100644 --- 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 @@ -26,7 +26,7 @@ Please edit this page to add any relevant new site that we are missing. ## Lnswap -[LNSWAP](https://www.lnswap.org). Non custiodial crypto currency exchange +[LNSWAP](https://www.lnswap.org). Non-custodial crypto currency exchange ![](/img/sh_lnswap.png) @@ -41,4 +41,3 @@ Please edit this page to add any relevant new site that we are missing. [Stackswap](https://app.stackswap.org/v2) ![](/img/sh_stackswap.png) - From 6f31aaceeaacb093afcb19bca64eca60caf96566 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:46:26 +0100 Subject: [PATCH 0593/1444] New translations more.md (Vietnamese) --- .../current/services-using-stacks/more.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) 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 index df0b3e2254..1e14b9a5a5 100644 --- 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 @@ -18,6 +18,6 @@ Please edit this page to add any relevant new site that we are missing. ## Sigle -[Sigle](https://www.sigle.io/) is a decentralised and open source web 3 writing platform. +[Sigle](https://www.sigle.io/) is a decentralized and open source web 3 writing platform. -![](/img/sh_sigle.png) \ No newline at end of file +![](/img/sh_sigle.png) From b937a9c97dd0b42eaf413dcc916237997326d81f Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:46:27 +0100 Subject: [PATCH 0594/1444] New translations nft.md (Vietnamese) --- .../current/services-using-stacks/nft.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) 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 index abb770663c..d582604854 100644 --- 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 @@ -15,6 +15,7 @@ Please edit this page to add any relevant new site that we are missing. ![website-screenshot](/img/sh_nft_byzantion.png) ### [Gamma](https://gamma.io/) + ![website-screenshot](/img/sh_nft_gamma.png) ### [Megapont](https://www.megapont.com/) @@ -35,4 +36,4 @@ Please edit this page to add any relevant new site that we are missing. ### [Superfandom](https://superfandom.io/) -![website-screenshot](/img/sh_superfandom.png) \ No newline at end of file +![website-screenshot](/img/sh_superfandom.png) From 7c1d4c36f7640004ef5a99b91ddad84150fc3bbb Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:46:28 +0100 Subject: [PATCH 0595/1444] New translations stacks-info-sites.md (Vietnamese) --- .../current/services-using-stacks/stacks-info-sites.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) 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 index 35ced8dac6..54f6823e33 100644 --- 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 @@ -30,7 +30,7 @@ Please edit this page to add any relevant new site that we are missing. ![website-screenshot](/img/sh_stxstats.png) -### [Novuminsights](https://stacks.novuminsights.com/health) +### [Novum Insights](https://stacks.novuminsights.com/health) ![website-screenshot](/img/sh_novuminsights.png) From 81677e5afdab107b34bd245fcf86744e86c600a7 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:46:29 +0100 Subject: [PATCH 0596/1444] New translations wallets.md (Vietnamese) --- .../current/services-using-stacks/wallets.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) 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 index e5ea6c5b45..2d3fcc85f2 100644 --- 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 @@ -15,6 +15,7 @@ Please edit this page to add any relevant new site that we are missing. [Blockchain.com](https://www.blockchain.com/wallet) ![](/img/sh_blockchain.png) + ## Boom [Boom](https://boom.money) @@ -26,6 +27,7 @@ Please edit this page to add any relevant new site that we are missing. [D'CENT](https://dcentwallet.com) ![](/img/sh_dcent.png) + ## Hiro Wallet [Hiro Wallet](https://www.hiro.so/wallet) @@ -48,4 +50,4 @@ Please edit this page to add any relevant new site that we are missing. [Wise](https://wiseapp.id) -![](/img/sh_wiseapp.png) \ No newline at end of file +![](/img/sh_wiseapp.png) From 1f1446c1e6ba79678db8b980346ff32b7d94426f Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:46:30 +0100 Subject: [PATCH 0597/1444] New translations whitepapers.md (Vietnamese) --- .../current/stacks-academy/whitepapers.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) create mode 100644 i18n/vi/docusaurus-plugin-content-docs/current/stacks-academy/whitepapers.md diff --git a/i18n/vi/docusaurus-plugin-content-docs/current/stacks-academy/whitepapers.md b/i18n/vi/docusaurus-plugin-content-docs/current/stacks-academy/whitepapers.md new file mode 100644 index 0000000000..0e564fbf44 --- /dev/null +++ b/i18n/vi/docusaurus-plugin-content-docs/current/stacks-academy/whitepapers.md @@ -0,0 +1,12 @@ +--- +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) From 4327fd5fa19fd782515db94f23700204026d05f1 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:46:31 +0100 Subject: [PATCH 0598/1444] New translations stacking-contract.md (Vietnamese) --- .../noteworthy-contracts/stacking-contract.md | 352 ++++++++++++++++++ 1 file changed, 352 insertions(+) create mode 100644 i18n/vi/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/stacking-contract.md diff --git a/i18n/vi/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/stacking-contract.md b/i18n/vi/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/stacking-contract.md new file mode 100644 index 0000000000..c0027256cd --- /dev/null +++ b/i18n/vi/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/stacking-contract.md @@ -0,0 +1,352 @@ +--- +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. 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` From e46dd6fa582fb4832c2536744121b49e4e3ee6f4 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:46:32 +0100 Subject: [PATCH 0599/1444] New translations index.md (Vietnamese) --- .../current/next-steps/index.md | 39 +++++++++++++++++++ 1 file changed, 39 insertions(+) create mode 100644 i18n/vi/docusaurus-plugin-content-docs/current/next-steps/index.md diff --git a/i18n/vi/docusaurus-plugin-content-docs/current/next-steps/index.md b/i18n/vi/docusaurus-plugin-content-docs/current/next-steps/index.md new file mode 100644 index 0000000000..00ddec9178 --- /dev/null +++ b/i18n/vi/docusaurus-plugin-content-docs/current/next-steps/index.md @@ -0,0 +1,39 @@ +--- +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) From 31401968fa5a330266259790e0900d0ecdf08937 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:46:32 +0100 Subject: [PATCH 0600/1444] New translations sips.md (Vietnamese) --- .../current/stacks-academy/sips.md | 52 +++++++++++++++++++ 1 file changed, 52 insertions(+) create mode 100644 i18n/vi/docusaurus-plugin-content-docs/current/stacks-academy/sips.md diff --git a/i18n/vi/docusaurus-plugin-content-docs/current/stacks-academy/sips.md b/i18n/vi/docusaurus-plugin-content-docs/current/stacks-academy/sips.md new file mode 100644 index 0000000000..aa2db18e62 --- /dev/null +++ b/i18n/vi/docusaurus-plugin-content-docs/current/stacks-academy/sips.md @@ -0,0 +1,52 @@ +--- +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/IJ15791776) 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-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. From 5e0f0ce2cfb979fcbef667a11961e4092a2cd247 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:46:33 +0100 Subject: [PATCH 0601/1444] New translations hosted-nodes.md (Vietnamese) --- .../current/nodes-and-miners/hosted-nodes.md | 25 +++++++++++++++++++ 1 file changed, 25 insertions(+) create mode 100644 i18n/vi/docusaurus-plugin-content-docs/current/nodes-and-miners/hosted-nodes.md diff --git a/i18n/vi/docusaurus-plugin-content-docs/current/nodes-and-miners/hosted-nodes.md b/i18n/vi/docusaurus-plugin-content-docs/current/nodes-and-miners/hosted-nodes.md new file mode 100644 index 0000000000..12d86c7ee2 --- /dev/null +++ b/i18n/vi/docusaurus-plugin-content-docs/current/nodes-and-miners/hosted-nodes.md @@ -0,0 +1,25 @@ +--- +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. From e4b53e3d260b85c9272422ac7fb63cee399d8fe0 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:46:34 +0100 Subject: [PATCH 0602/1444] New translations authentication.md (Portuguese, Brazilian) --- .../current/stacks-academy/authentication.md | 63 +++++++++++++++++++ 1 file changed, 63 insertions(+) create mode 100644 i18n/pt/docusaurus-plugin-content-docs/current/stacks-academy/authentication.md diff --git a/i18n/pt/docusaurus-plugin-content-docs/current/stacks-academy/authentication.md b/i18n/pt/docusaurus-plugin-content-docs/current/stacks-academy/authentication.md new file mode 100644 index 0000000000..8152a401f9 --- /dev/null +++ b/i18n/pt/docusaurus-plugin-content-docs/current/stacks-academy/authentication.md @@ -0,0 +1,63 @@ +--- +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/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. From 1422af6b6fc92aedc7c5b9568b3117cd1a80a313 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:46:35 +0100 Subject: [PATCH 0603/1444] New translations bns.md (Portuguese, Brazilian) --- .../current/stacks-academy/bns.md | 239 ++++++++++++++++++ 1 file changed, 239 insertions(+) create mode 100644 i18n/pt/docusaurus-plugin-content-docs/current/stacks-academy/bns.md diff --git a/i18n/pt/docusaurus-plugin-content-docs/current/stacks-academy/bns.md b/i18n/pt/docusaurus-plugin-content-docs/current/stacks-academy/bns.md new file mode 100644 index 0000000000..d105ef69cf --- /dev/null +++ b/i18n/pt/docusaurus-plugin-content-docs/current/stacks-academy/bns.md @@ -0,0 +1,239 @@ +--- +title: Blockchain Naming System +description: Binds Stacks usernames to off-chain state +sidebar_position: 8 +--- + +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 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). From 56745c28c8093b09250b9b0b6ab371e883095388 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:46:36 +0100 Subject: [PATCH 0604/1444] New translations docs.md (Portuguese, Brazilian) --- .../current/contribute/docs.md | 24 ++++++++++++------- 1 file changed, 15 insertions(+), 9 deletions(-) diff --git a/i18n/pt/docusaurus-plugin-content-docs/current/contribute/docs.md b/i18n/pt/docusaurus-plugin-content-docs/current/contribute/docs.md index 77705451b8..b2fef628f9 100644 --- a/i18n/pt/docusaurus-plugin-content-docs/current/contribute/docs.md +++ b/i18n/pt/docusaurus-plugin-content-docs/current/contribute/docs.md @@ -7,7 +7,7 @@ description: Learn how this site is built, and how you can contribute to it. 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). +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/). @@ -15,7 +15,7 @@ Don't want to learn it? No need to. Write [in plain text an issue on Github](htt :::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 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). @@ -24,28 +24,32 @@ To add new content, they are two different ways to do it, the [easy way](#easy-w [**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. +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 yourhanges in real time. + - `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. -## Aditional information +## 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 ``` @@ -54,8 +58,8 @@ Before running this command for the first time you will need to run `npm install 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 ``` @@ -91,7 +95,7 @@ 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. +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 @@ -124,6 +128,7 @@ And execute prettier with the following command: npx prettier --write mynewfiletocheck.md ``` --> + ### 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. @@ -138,6 +143,7 @@ To write a code block, you need to wrap your code in ` ```language `, and end yo (define-public (get-counter) (ok (var-get counter))) ``` + ### Admonitions You can use the following admonitions to highlight content. @@ -204,4 +210,4 @@ Some **content** with _markdown_ `syntax`. Some **content** with _markdown_ `syntax`. -::: \ No newline at end of file +::: From 2c30055f347b1e351fd33d66346f43bc79c412be Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:46:37 +0100 Subject: [PATCH 0605/1444] New translations translations.md (Portuguese, Brazilian) --- .../current/contribute/translations.md | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/i18n/pt/docusaurus-plugin-content-docs/current/contribute/translations.md b/i18n/pt/docusaurus-plugin-content-docs/current/contribute/translations.md index 49a9d366ad..fb9977f707 100644 --- a/i18n/pt/docusaurus-plugin-content-docs/current/contribute/translations.md +++ b/i18n/pt/docusaurus-plugin-content-docs/current/contribute/translations.md @@ -1,24 +1,23 @@ --- title: Contribute with translations -description: Want to help tranlating these docs to your local language? +description: Want to help translating 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. +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 Crodin intead. +:::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 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 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) From 33f623fd8348e7b716ca1e80384b3d399875e9cb Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:46:39 +0100 Subject: [PATCH 0606/1444] New translations gaia-on-ec2.md (Portuguese, Brazilian) --- .../current/gaia/gaia-on-ec2.md | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) 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 index 8f2b139876..1ba301b42d 100644 --- 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 @@ -26,9 +26,10 @@ Use a link in the table to launch the [CloudFormation](https://console.aws.amazo ### Step 2 - Setup stack using template -You need to configure the template with the appropiate values for your hub and domain it runs on. +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 ``` @@ -52,7 +53,7 @@ Specify the stack details and then click `Next`: ![Specify template](/img/cloudf | 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`. | +| 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 | @@ -90,7 +91,9 @@ ssh -i admin@ 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 +![](/img/cloudformation-gaia-template1-designer.png) From dd5eacf839b61f72a91d992d1435a0cb5ea25ac4 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:46:40 +0100 Subject: [PATCH 0607/1444] New translations gaia.md (Portuguese, Brazilian) --- .../current/gaia/gaia.md | 12 +++++++++--- 1 file changed, 9 insertions(+), 3 deletions(-) diff --git a/i18n/pt/docusaurus-plugin-content-docs/current/gaia/gaia.md b/i18n/pt/docusaurus-plugin-content-docs/current/gaia/gaia.md index db5f975f8e..e0cba7aa86 100644 --- a/i18n/pt/docusaurus-plugin-content-docs/current/gaia/gaia.md +++ b/i18n/pt/docusaurus-plugin-content-docs/current/gaia/gaia.md @@ -1,14 +1,20 @@ --- title: Gaia description: Decentralized storage architecture for off-chain data -sidebar_position: 5 +sidebar_position: 6 tags: - gaia --- ## Introduction -Apps built with the Stacks blockchain store off-chain data using a storage system called Gaia. +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. @@ -38,7 +44,7 @@ The Stacks blockchain stores only identity data. Data created by the actions of 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) +![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. From aa0eae1a99a288b4a3de8bef803ae916cb55b992 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:46:41 +0100 Subject: [PATCH 0608/1444] New translations setup-linux.md (Portuguese, Brazilian) --- .../current/gaia/setup-linux.md | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) 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 index 1338c8f865..f034f95503 100644 --- a/i18n/pt/docusaurus-plugin-content-docs/current/gaia/setup-linux.md +++ b/i18n/pt/docusaurus-plugin-content-docs/current/gaia/setup-linux.md @@ -1,6 +1,6 @@ --- 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. +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 @@ -19,7 +19,7 @@ This configuration will setup the following 4 docker containers: apt update && apt upgrade -y && apt install -y git vim gnupg jq ``` -**3. Clone the GAIA repository** and enter it's docker directory. +**3. 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 @@ -47,8 +47,7 @@ chmod +x ${DESTINATION_DC}/docker-compose 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. +**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 From 98107251f54a5161938a864adf7dc7a0680a53e6 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:46:43 +0100 Subject: [PATCH 0609/1444] New translations digitalocean.md (Portuguese, Brazilian) --- .../current/nodes-and-miners/digitalocean.md | 41 +++++++++++-------- 1 file changed, 25 insertions(+), 16 deletions(-) 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 index dd7194f504..15df918d04 100644 --- 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 @@ -1,28 +1,30 @@ --- -title: Stacks on DigitalOcean +title: Run a Node with Digital Ocean description: A guide to setup Stacks on DigitalOcean -sidebar_position: 4 +sidebar_position: 2 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). +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`. +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 plan that meets the minimum requirements) and your prefered datacenter region. ![](/img/sh_digitalocean-choose-plan.png) +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 if your prefer. +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) @@ -46,41 +48,48 @@ Congratulations! You are now running the Stacks Blockchain. You can click on `Co ## 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). +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`. -Once the stacks blockchain starts to sync with peers, application ports will open and nginx port 80 will now start proxying requests. +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 v3.0.3 (master:cd0c8aef)", + "server_version": "stacks-blockchain-api v6.2.3 (master:77ab3ae2)", "status": "ready", "chain_tip": { - "block_height": 16220, - "block_hash": "0x3123fba9c0de6b569573494cf83c1d5d198a66bfd5f48ef97949b6bf11ba13be", - "index_block_hash": "0xeec960fbbd6186b4ccac85ce12adba72be497d881f81e077305c90955b51a6ae" + "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/README.md#quickstart). +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). -## API Creation +## 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 -curl -X POST -H 'Content-Type: application/json' \ +$ export TOKEN= +$ 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"}' \ + '{"name":"stacks-blockchain","region":"sfo2","size":"s-2vcpu-4gb","image":"stacksfoundation-stacksblockchain"}' \ "https://api.digitalocean.com/v2/droplets" ``` From 43f0c8c1254080bfbf80aec8c9a761887e0ddc52 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:46:44 +0100 Subject: [PATCH 0610/1444] New translations index.md (Portuguese, Brazilian) --- .../current/nodes-and-miners/index.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) 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 index b6cbb9754a..e5f4f2c250 100644 --- 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 @@ -1,11 +1,11 @@ --- title: Nodes and Miners description: Nodes and Miners -sidebar_position: 7 +sidebar_position: 5 --- -Here are all the steps to run nodes and miners, both on mainnet and testnet. +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. -## What's a Stacks node? +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. -## What's a Stacks miner? +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. From 382387a12f1492c66a2dfa296b12814f0be48d9b Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:46:45 +0100 Subject: [PATCH 0611/1444] New translations miner-mainnet.md (Portuguese, Brazilian) --- .../current/nodes-and-miners/miner-mainnet.md | 300 +++++++----------- 1 file changed, 110 insertions(+), 190 deletions(-) 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 index 941ff9ac13..5afd34c23f 100644 --- 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 @@ -1,166 +1,100 @@ --- title: Mine mainnet Stacks tokens -description: Set up and run a miner on the Stacks 2.0 mainnet -sidebar_position: 5 +description: Set up and run a miner on Stacks Mainnet +sidebar_position: 6 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. +For more on the technical details of mining, please review the [mining guide](../stacks-academy/mining) -If you're interested in mining on the testnet, you can find instructions on how to do that [here](miner-testnet): +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 want to learn more about the technical details of mining, please review the [mining guide](../understand-stacks/mining): +If you're interested in mining on the Stacks testnet, you can find instructions on how to do that [here](miner-testnet): -## Running bitcoind locally +## Running a Bitcoin Mainnet Full Node -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) +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. -First, download the bitcoind software for your platform from https://bitcoin.org/en/download. +- [Ensure your computer meets the minimum hardware requirements before continuing.](https://bitcoin.org/en/bitcoin-core/features/requirements#system-requirements) -Next, start bitcoind with the following configuration: +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): -```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 -``` - - +:::tip It is recommened to use a persistent location for the chainstate, in the steps below we're using `/bitcoin` ::: -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 Bitcoin Configuration File - +Next, update the bitcoin configuration: -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: +- **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 -[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 = "" -... +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 ``` -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. +### Start Bitcoin -To run your miner, run this in the command line: +Finally, start bitcoin as follows (adjust the `conf` path to where it was created in the previous step, i.e. `$HOME/bitcoin.conf`): ```bash -stacks-node start --config=./testnet/stacks-node/conf/mainnet-miner-conf.toml +bitcoind -conf=$HOME/bitcoin.conf ``` -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 -``` +:::note +It will take a few days for the node to synchronize with Bitcoin mainnet. +::: -The above code will compile an optimized binary. To use it, run: +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 -cd ../.. -./target/release/stacks-node start --config=./mainnet-miner-conf.toml +$ bitcoin-cli \ + -rpcconnect=localhost \ + -rpcport=8332 \ + -rpcuser=btcuser \ + -rpcpassword=btcpassword \ +getblockchaininfo | jq .blocks +773281 ``` -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 +## Running a Stacks Blockchain miner -### Prerequisites +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) -Make sure are [running a node](run-a-node) and [running bitcoind locally](#running-bitcoind-locally) before starting this tutorial. +_There may be some extra requirements to building, [defined here](https://github.com/stacksfoundation/miner-docs/blob/main/prerequisites.md#install-required-packages)_ -### Generate keychain and get mainnet tokens in Windows +:::tip It is recommened to use a persistent location for the chainstate, in the steps below we're using `/stacks-blockchain` ::: -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. +### Generate a keychain -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`. +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. -Generate a keychain: +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 -npm install --global @stacks/cli -stx make_keychain > cli_keychain.json -type cli_keychain.json +npx @stacks/cli make_keychain 2>/dev/null | jq -r ``` -After this runs, you'll probably see some installation logs, and at the end you should see some JSON that looks like this: +After this runs, you should see some JSON printed to the screen that looks like this: ```json { @@ -174,108 +108,99 @@ After this runs, you'll probably see some installation logs, and at the end you } ``` -:::tip Check out the [Stacks CLI reference](https://docs.hiro.so/references/stacks-cli) for more details ::: +:::warning **Do not lose this information** - we'll need to use the `privateKey` and `btcAddress` fields in later steps. ::: -The above BTC address will then need to be imported into the BTC network. +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=your-user -rpcpassword=your-password importaddress +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 configuration file + + +### 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. -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). +Next, update the bitcoin configuration: -Update the following properties: +- **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] -... -# Enter your private key here -seed = "replace-with-your-private-key" -local_peer_seed = "replace-with-your-private-key" -... +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] -... -# To mine on mainnet, you need to run bitcoind locally -# Details can be found in above section, 'Running bitcoind locally' +chain = "bitcoin" +mode = "mainnet" peer_host = "127.0.0.1" -username = "" -password = "" -... +username = "" +password = "" +rpc_port = 8332 +peer_port = 8333 +satoshis_per_byte = 100 +burn_fee_cap = 20000 ``` -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 Stacks Blockchain -### Run the miner - -To start your miner, run this in the command line: +To run your miner, run this in the command line: ```bash -stacks-node start --config=testnet/stacks-node/conf/mainnet-miner-conf.toml +stacks-node start --config=$HOME/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 +### 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 -set RUST_BACKTRACE=full; -set STACKS_LOG_DEBUG=1; -stacks-node start --config=mainnet-miner-conf.toml +STACKS_LOG_DEBUG=1 stacks-node start --config=$HOME/mainnet-miner-conf.toml ``` -## Optional: Running with Docker +--- + +## Optional: Running a Stacks Blockchain miner with Docker -Alternatively, you can run the mainnet node with Docker. +Alternatively, you can run a Stacks mainnet miner with Docker. -:::caution Ensure you have [Docker](https://docs.docker.com/get-docker/) installed on your machine. ::: +:::caution Ensure you have [Docker](https://docs.docker.com/get-docker/) installed. ::: -### Generate keychain and get tokens +### 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 +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 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: +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). -```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 = "" -... -``` +### Update Stacks Blockchain Docker Configuration File -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. +Use the steps oulined above to create the [configuration file](miner-mainnet#update-the-stacks-blockchain-configuration-file) -### Start the miner +### 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 ::: @@ -286,7 +211,8 @@ docker run -d \ --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" \ + -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 \ @@ -301,9 +227,9 @@ 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). +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 on your machine: +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) @@ -312,13 +238,7 @@ Ensure you have the following prerequisites installed on your machine: ### 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). +Use the steps [outlined above](miner-mainnet#generate-a-keychain-and-get-some-tokens) ### Install the chart and run the miner From 7e958b969c8b19d1edaf9191a5979666711e0a14 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:46:46 +0100 Subject: [PATCH 0612/1444] New translations miner-testnet.md (Portuguese, Brazilian) --- .../current/nodes-and-miners/miner-testnet.md | 317 +++++++----------- 1 file changed, 130 insertions(+), 187 deletions(-) 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 index 1bee3a9923..c0a27e63d5 100644 --- 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 @@ -1,35 +1,52 @@ --- title: Mine testnet Stacks tokens -description: Set up and run a miner on the Stacks 2.0 testnet -sidebar_position: 4 +description: Set up and run a miner on Stacks Testnet +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 testnet. +For more on the technical details of mining, please review the [mining guide](../stacks-academy/mining) -If you want to learn more about the technical details of mining, please review the [mining guide](../understand-stacks/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)). -## Running bitcoind locally +If you're interested in mining on the Stacks mainnet, you can find instructions on how to do that [here](miner-mainnet): -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) +## Running a Bitcoin Testnet Full Node -First, download the bitcoind software for your platform from https://bitcoin.org/en/download. +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. -Next, start bitcoind with the following configuration: +- [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 -rpcuser=your-bitcoind-username -rpcpassword=your-bitcoind-password testnet=1 -txindex=0 -listen=1 -rpcserialversion=0 -maxorphantx=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 @@ -37,126 +54,51 @@ 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. +### Start Bitcoin -To run your miner, run this in the command line: +Finally, start bitcoind as follows: ```bash -stacks-node start --config=./testnet/stacks-node/conf/testnet-miner-conf.toml +bitcoind -conf=$HOME/bitcoin.conf ``` -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 -``` +:::note +It will take a few hours for the node to synchronize with Bitcoin testnet. +::: -The above code will compile an optimized binary. To use it, run: +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 -cd ../.. -./target/release/stacks-node start --config=./testnet/conf/testnet-follower-conf.toml +$ bitcoin-cli \ + -rpcconnect=localhost \ + -rpcport=18332 \ + -rpcuser=btcuser \ + -rpcpassword=btcpass \ +getblockchaininfo | jq .blocks +2417570 ``` -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 +## Running a Stacks Blockchain miner -### Prerequisites +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) -Make sure are [running a testnet node](run-a-node) before starting this tutorial. +_There may be some extra requirements to building, [defined here](https://github.com/stacksfoundation/miner-docs/blob/main/prerequisites.md#install-required-packages)_ -### Generate keychain and get testnet tokens in Windows +:::tip It is recommened to use a persistent location for the chainstate, in the steps below we're using `/stacks-blockchain` ::: -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. +### Generate a keychain -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. +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. -Generate a keychain: +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 -npm install --global @stacks/cli -stx make_keychain -t > cli_keychain.json -type cli_keychain.json +npx @stacks/cli make_keychain -t 2>/dev/null | jq -r ``` -After this runs, you'll probably see some installation logs, and at the end you should see some JSON that looks like this: +After this runs, you should see some JSON printed to the screen that looks like this: ```json { @@ -170,106 +112,110 @@ After this runs, you'll probably see some installation logs, and at the end you } ``` -:::tip Check out the [Stacks CLI reference](https://docs.hiro.so/references/stacks-cli) for more details ::: +:::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. -Request BTC from faucet: +### Update the Stacks Blockchain Configuration File -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/). +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`. -### Update configuration file +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. -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). +Next, update the bitcoin configuration: -Update the following properties: +- **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] -... -seed = "replace-with-your-private-key" -local_peer_seed = "replace-with-your-private-key" -... +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] -... -# To mine on Testnet, you need to run bitcoind locally -# Details can be found in above section, 'Running bitcoind locally' +chain = "bitcoin" +mode = "xenon" peer_host = "127.0.0.1" -username = "" -password = "" -... +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 ``` -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 Stacks Blockchain -### Run the miner - -To start your miner, run this in the command line: +To run your miner, run this in the command line: ```bash -stacks-node start --config=testnet/stacks-node/conf/testnet-miner-conf.toml +stacks-node start --config=$HOME/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 +### 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 -set RUST_BACKTRACE=full; -set STACKS_LOG_DEBUG=1; -stacks-node start --config=testnet-miner-conf.toml +STACKS_LOG_DEBUG=1 stacks-node start --config=$HOME/testnet-miner-conf.toml ``` -## Optional: Running with Docker +--- + +## Optional: Running a Stacks Blockchain miner with Docker -Alternatively, you can run the testnet node with Docker. +Alternatively, you can run a Stacks testnet miner with Docker. -:::warning Ensure you have [Docker](https://docs.docker.com/get-docker/) installed on your machine. ::: +:::caution Ensure you have [Docker](https://docs.docker.com/get-docker/) installed ::: -### Generate keychain and get testnet tokens +### Generate a Keychain and Get Some Tokens Generate a keychain: ```bash -docker run -i node:14-alpine npx @stacks/cli make_keychain -t 2>/dev/null +docker run -i node:14-alpine npx @stacks/cli make_keychain 2>/dev/null | jq -r ``` -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 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. -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 Stacks Blockchain Docker Configuration File -Update the following properties: +Use the steps oulined above to create the [configuration file](miner-testnet#update-the-stacks-blockchain-configuration-file) -```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 +### 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 ::: @@ -280,7 +226,8 @@ docker run -d \ --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" \ + -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 \ @@ -293,26 +240,22 @@ You can review the node logs with this command: 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). +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 on your machine: +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 testnet tokens - -Generate a keychain: - -```bash -docker run -i node:14-alpine npx @stacks/cli make_keychain -t 2>/dev/null -``` +### Generate keychain and get some tokens -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/). +Use the steps [outlined above](miner-testnet#generate-a-keychain-and-get-some-tokens) ### Install the chart and run the miner @@ -323,7 +266,7 @@ 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.node.seed="replace-with-your-privateKey-from-generate-keychain-step" \ ``` You can review the node logs with this command: From b073fbd8a86f0d2f434430689f2b026a7cc007cf Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:46:47 +0100 Subject: [PATCH 0613/1444] New translations stacks-node-configuration.md (Portuguese, Brazilian) --- .../stacks-node-configuration.md | 166 +++++++++++------- 1 file changed, 106 insertions(+), 60 deletions(-) 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 index 9ea58d7a89..cd216e7103 100644 --- 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 @@ -1,7 +1,7 @@ --- title: Stacks Node Configuration description: Configuration parameters and options for the stacks-node binary -sidebar_position: 6 +sidebar_position: 4 --- ## Usage @@ -10,97 +10,141 @@ sidebar_position: 6 stacks-node sub-command [--subcommand-option ] ``` -## Subcommands +### 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 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 -### mocknet +## Configuration File Options -Start a node based on a fast local setup emulating a burnchain. Ideal for smart contract development. +The Stacks Blockchain configuration file has multiple sections under which an option may be placed. -Example: +- [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) -```bash -stacks-node mocknet -``` +For reference, several configuration file examples are [available here](https://github.com/stacks-network/stacks-blockchain/tree/master/testnet/stacks-node/conf) -### krypton +- [Example mainnet follower configuration](./stacks-node-configuration#example-mainnet-follower-configuration) -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). +### node -Example: +Contains various configuration options for the stacks-node binary. -```bash -stacks-node krypton -``` +| 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. | -### testnet +### events_observer -Start a node that will join and stream blocks from the public testnet. +:::info This section is _optional_ and not required -Example: +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. -```bash -stacks-node testnet -``` +| 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. | | -### mainnet +### connection_options -Start a node that joins and streams blocks from the public mainnet. +:::info This section is _optional_ and not required. -Example: +However, if this section is added, **all** fields are required ::: -```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. +Specifies configuration options for others connecting to the stacks node. -#### Arguments +| 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 | -**--config**: relative or absolute path to the TOML config file. Required. +### burnchain -Example: +This section contains configuration options pertaining to the blockchain the stacks-node binds to on the backend for proof-of-transfer (BTC). -```bash -stacks-node start --config=/path/to/config.toml -``` +| 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` | -See [Configuration File Options](#configuration-file-options) for more information. +#### Mining -#### version +| 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`. | -Displays information about the current version and the release cycle. +### ustx_balance -Example: +- `mocknet`/`testnet` only -```bash -stacks-node version -``` +This section contains configuration options allocating microSTX per address in the genesis block -#### help +This section can repeat multiple times, but each section can only define a single address. -Displays a help message. +:::info This section is only required for the `testnet` and `mocknet` networks. -Example: +However, if this section is added, **all** fields are required ::: -```bash -stacks-node help -``` +| 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 | -## Configuration File Options +## Example Mainnet Follower Configuration -The TOML configuration file has multiple sections under which an option may be placed. +```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" -To see a list of example configurations, [please see this page](https://github.com/stacks-network/stacks-blockchain/tree/master/testnet/stacks-node/conf). +[burnchain] +chain = "bitcoin" +mode = "mainnet" +peer_host = "localhost" +username = "user" +password = "pass" +rpc_port = 8332 +peer_port = 8333 -### Section: node +[[events_observer]] +endpoint = "localhost:3700" +retry_count = 255 +events_keys = ["*"] +``` -Contains various configuration options pertaining to the stacks-node. -Example: + From 0d8d350578eabea01b8096061a0ba511cae926c2 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:46:47 +0100 Subject: [PATCH 0614/1444] New translations accounts.md (Portuguese, Brazilian) --- .../current/stacks-academy/accounts.md | 212 ++++++++++++++++++ 1 file changed, 212 insertions(+) create mode 100644 i18n/pt/docusaurus-plugin-content-docs/current/stacks-academy/accounts.md diff --git a/i18n/pt/docusaurus-plugin-content-docs/current/stacks-academy/accounts.md b/i18n/pt/docusaurus-plugin-content-docs/current/stacks-academy/accounts.md new file mode 100644 index 0000000000..8383157394 --- /dev/null +++ b/i18n/pt/docusaurus-plugin-content-docs/current/stacks-academy/accounts.md @@ -0,0 +1,212 @@ +--- +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" + } + } + ] +} +``` From 07ed195fe15fa9da6257224d9264ac13483effad Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:46:48 +0100 Subject: [PATCH 0615/1444] New translations microblocks.md (Portuguese, Brazilian) --- .../current/stacks-academy/microblocks.md | 106 ++++++++++++++++++ 1 file changed, 106 insertions(+) create mode 100644 i18n/pt/docusaurus-plugin-content-docs/current/stacks-academy/microblocks.md diff --git a/i18n/pt/docusaurus-plugin-content-docs/current/stacks-academy/microblocks.md b/i18n/pt/docusaurus-plugin-content-docs/current/stacks-academy/microblocks.md new file mode 100644 index 0000000000..9fd7b8209d --- /dev/null +++ b/i18n/pt/docusaurus-plugin-content-docs/current/stacks-academy/microblocks.md @@ -0,0 +1,106 @@ +--- +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. + +[provides an endpoint]: https://docs.hiro.so/get-started/stacks-blockchain-api#nonce-handling +[microblocks_api]: https://docs.hiro.so/api#tag/Microblocks From 23183c311dbeedae39439d9879fe8188a60b1b1a Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:46:49 +0100 Subject: [PATCH 0616/1444] New translations mining.md (Portuguese, Brazilian) --- .../current/stacks-academy/mining.md | 83 +++++++++++++++++++ 1 file changed, 83 insertions(+) create mode 100644 i18n/pt/docusaurus-plugin-content-docs/current/stacks-academy/mining.md diff --git a/i18n/pt/docusaurus-plugin-content-docs/current/stacks-academy/mining.md b/i18n/pt/docusaurus-plugin-content-docs/current/stacks-academy/mining.md new file mode 100644 index 0000000000..78a0711ebd --- /dev/null +++ b/i18n/pt/docusaurus-plugin-content-docs/current/stacks-academy/mining.md @@ -0,0 +1,83 @@ +--- +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 From e91ac419625a7a3545cae622a2dea606f6b84638 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:46:50 +0100 Subject: [PATCH 0617/1444] New translations network.md (Portuguese, Brazilian) --- .../current/stacks-academy/network.md | 149 ++++++++++++++++++ 1 file changed, 149 insertions(+) create mode 100644 i18n/pt/docusaurus-plugin-content-docs/current/stacks-academy/network.md diff --git a/i18n/pt/docusaurus-plugin-content-docs/current/stacks-academy/network.md b/i18n/pt/docusaurus-plugin-content-docs/current/stacks-academy/network.md new file mode 100644 index 0000000000..2d1b9585b4 --- /dev/null +++ b/i18n/pt/docusaurus-plugin-content-docs/current/stacks-academy/network.md @@ -0,0 +1,149 @@ +--- +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 +} +``` From c1d81d516bb4b8c638527775267a9af31088c019 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:46:51 +0100 Subject: [PATCH 0618/1444] New translations stacking.md (Portuguese, Brazilian) --- .../current/stacks-academy/stacking.md | 148 ++++++++++++++++++ 1 file changed, 148 insertions(+) create mode 100644 i18n/pt/docusaurus-plugin-content-docs/current/stacks-academy/stacking.md diff --git a/i18n/pt/docusaurus-plugin-content-docs/current/stacks-academy/stacking.md b/i18n/pt/docusaurus-plugin-content-docs/current/stacks-academy/stacking.md new file mode 100644 index 0000000000..542b62f70f --- /dev/null +++ b/i18n/pt/docusaurus-plugin-content-docs/current/stacks-academy/stacking.md @@ -0,0 +1,148 @@ +--- +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. 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. + +![](/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 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 (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 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) From 784b07988194af99ab79b981a60092523c23ed24 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:46:52 +0100 Subject: [PATCH 0619/1444] New translations technical-specs.md (Portuguese, Brazilian) --- .../current/stacks-academy/technical-specs.md | 79 +++++++++++++++++++ 1 file changed, 79 insertions(+) create mode 100644 i18n/pt/docusaurus-plugin-content-docs/current/stacks-academy/technical-specs.md diff --git a/i18n/pt/docusaurus-plugin-content-docs/current/stacks-academy/technical-specs.md b/i18n/pt/docusaurus-plugin-content-docs/current/stacks-academy/technical-specs.md new file mode 100644 index 0000000000..695f849e1a --- /dev/null +++ b/i18n/pt/docusaurus-plugin-content-docs/current/stacks-academy/technical-specs.md @@ -0,0 +1,79 @@ +--- +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). +- 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 whitepaper v2](https://www.youtube.com/watch?v=Wd-Bfe8Sn-Y). From ba3f27ac0d19ad871cff8e8f2ec9781dd0654e68 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:46:52 +0100 Subject: [PATCH 0620/1444] New translations testnet.md (Portuguese, Brazilian) --- .../current/stacks-academy/testnet.md | 35 +++++++++++++++++++ 1 file changed, 35 insertions(+) create mode 100644 i18n/pt/docusaurus-plugin-content-docs/current/stacks-academy/testnet.md diff --git a/i18n/pt/docusaurus-plugin-content-docs/current/stacks-academy/testnet.md b/i18n/pt/docusaurus-plugin-content-docs/current/stacks-academy/testnet.md new file mode 100644 index 0000000000..f8b9f03df2 --- /dev/null +++ b/i18n/pt/docusaurus-plugin-content-docs/current/stacks-academy/testnet.md @@ -0,0 +1,35 @@ +--- +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. + +### 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) From 555e014a54ba19d3017a7047b5511026a011d415 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:46:53 +0100 Subject: [PATCH 0621/1444] New translations transactions.md (Portuguese, Brazilian) --- .../current/stacks-academy/transactions.md | 40 +++++++++++++++++++ 1 file changed, 40 insertions(+) create mode 100644 i18n/pt/docusaurus-plugin-content-docs/current/stacks-academy/transactions.md diff --git a/i18n/pt/docusaurus-plugin-content-docs/current/stacks-academy/transactions.md b/i18n/pt/docusaurus-plugin-content-docs/current/stacks-academy/transactions.md new file mode 100644 index 0000000000..ba6b18f0f7 --- /dev/null +++ b/i18n/pt/docusaurus-plugin-content-docs/current/stacks-academy/transactions.md @@ -0,0 +1,40 @@ +--- +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). ::: From 7856c232bb772a3d90fe1d36899f56a1847cc62d Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:46:55 +0100 Subject: [PATCH 0622/1444] New translations language-functions.md (Portuguese, Brazilian) --- .../current/clarity/language-functions.md | 2025 +++++++++++++++++ 1 file changed, 2025 insertions(+) create mode 100644 i18n/pt/docusaurus-plugin-content-docs/current/clarity/language-functions.md diff --git a/i18n/pt/docusaurus-plugin-content-docs/current/clarity/language-functions.md b/i18n/pt/docusaurus-plugin-content-docs/current/clarity/language-functions.md new file mode 100644 index 0000000000..ba247ab2f9 --- /dev/null +++ b/i18n/pt/docusaurus-plugin-content-docs/current/clarity/language-functions.md @@ -0,0 +1,2025 @@ +--- +title: Functions +description: See a detailed list of all functions for the Clarity language. +sidebar_position: 3 +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: + +#### 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-existent\"))))) ;; 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-existent\") ;; 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-existent\" })) ;; 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-existent\" }))) ;; 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-existent\" }))) ;; 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 \"Stacks\" '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 successfully 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_ transferred from another principal, but rather minted. + +If a non-positive amount is provided to mint, this function returns `(err 1)`. Otherwise, on successfully 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_ transferred 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 successfully 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 successfully 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)) +``` From 36adf5d74747eee7af3377c24cc3160beb8aadd1 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:46:56 +0100 Subject: [PATCH 0623/1444] New translations language-keywords.md (Portuguese, Brazilian) --- .../current/clarity/language-keywords.md | 146 ++++++++++++++++++ 1 file changed, 146 insertions(+) create mode 100644 i18n/pt/docusaurus-plugin-content-docs/current/clarity/language-keywords.md diff --git a/i18n/pt/docusaurus-plugin-content-docs/current/clarity/language-keywords.md b/i18n/pt/docusaurus-plugin-content-docs/current/clarity/language-keywords.md new file mode 100644 index 0000000000..1aca5359c3 --- /dev/null +++ b/i18n/pt/docusaurus-plugin-content-docs/current/clarity/language-keywords.md @@ -0,0 +1,146 @@ +--- +title: Keywords +description: See a detailed list of all keywords for the Clarity language. +sidebar_position: 4 +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 +``` From 06877dc3cb5b94af3041a3da29ba15a43f337c7c Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:46:56 +0100 Subject: [PATCH 0624/1444] New translations language-types.md (Portuguese, Brazilian) --- .../current/clarity/language-types.md | 25 +++++++++++++++++++ 1 file changed, 25 insertions(+) create mode 100644 i18n/pt/docusaurus-plugin-content-docs/current/clarity/language-types.md diff --git a/i18n/pt/docusaurus-plugin-content-docs/current/clarity/language-types.md b/i18n/pt/docusaurus-plugin-content-docs/current/clarity/language-types.md new file mode 100644 index 0000000000..0af4577dc9 --- /dev/null +++ b/i18n/pt/docusaurus-plugin-content-docs/current/clarity/language-types.md @@ -0,0 +1,25 @@ +--- +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. | From 2b611b1524c8db42f6e182657258a55cc325f1a6 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:46:58 +0100 Subject: [PATCH 0625/1444] New translations miner-costs-and-fees.md (Portuguese, Brazilian) --- .../current/nodes-and-miners/miner-costs-and-fees.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) 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 index 40397a51e0..dd8ee721cc 100644 --- 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 @@ -8,7 +8,7 @@ sidebar_position: 8 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 @@ -22,3 +22,5 @@ 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). From 580b47ed528f3384da8e5a35790cff0f812ea4ad Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:46:59 +0100 Subject: [PATCH 0626/1444] New translations verify-miner.md (Portuguese, Brazilian) --- .../current/nodes-and-miners/verify-miner.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) 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 index 094e3f03a1..18e8dd3a48 100644 --- 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 @@ -7,7 +7,7 @@ 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 +$ 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 -``` \ No newline at end of file +``` From 10b29211b3ac6525be6ae4ac3f838dc77f13920e Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:47:00 +0100 Subject: [PATCH 0627/1444] New translations stacks-blockchain-api.md (Portuguese, Brazilian) --- .../stacks-academy/stacks-blockchain-api.md | 41 +++++++++++++++++++ 1 file changed, 41 insertions(+) create mode 100644 i18n/pt/docusaurus-plugin-content-docs/current/stacks-academy/stacks-blockchain-api.md diff --git a/i18n/pt/docusaurus-plugin-content-docs/current/stacks-academy/stacks-blockchain-api.md b/i18n/pt/docusaurus-plugin-content-docs/current/stacks-academy/stacks-blockchain-api.md new file mode 100644 index 0000000000..ad9bb1822e --- /dev/null +++ b/i18n/pt/docusaurus-plugin-content-docs/current/stacks-academy/stacks-blockchain-api.md @@ -0,0 +1,41 @@ +--- +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`. ::: From b917057165436e6fb92ef14877f9e5a9ae9df5d5 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:47:01 +0100 Subject: [PATCH 0628/1444] New translations run-a-node.md (Portuguese, Brazilian) --- .../current/nodes-and-miners/run-a-node.md | 329 +++--------------- 1 file changed, 42 insertions(+), 287 deletions(-) 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 index 94d938c5ca..2993568ce4 100644 --- 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 @@ -1,5 +1,5 @@ --- -title: Run a node +title: Run a Node with Docker description: Set up and run a Stacks node sidebar_position: 1 tags: @@ -8,344 +8,99 @@ tags: ## Stacks Blockchain with Docker -Run your own Stacks Blockchain node easily with just few commands. +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) -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](./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) -## **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 -``` +## **Requirements:** -- With optional proxy: +The **minimum viable requirements** are listed below. -```bash -./manage.sh -n -a start -f proxy -``` +While you _can_ run a node using these specs, it's _recommended_ to assign more than the minimum for better performance. -- With optional bitcoin node: +- ⚠️ [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_ ) -```bash -./manage.sh -n -a start -f bitcoin -``` +:::caution MacOS with an ARM processor is NOT recommended -5. **Stop the Services** +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. ::: -```bash -./manage.sh -n -a stop -``` - -6. **Retrieve Service Logs** - -```bash -./manage.sh -n -a logs -``` - -- Export docker log files to `./exported-logs`: +## **Quickstart** -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. +The `` placeholder used below can be replaced with one of: -```bash -./manage.sh -n -a logs export -``` +- mainnet +- testnet +- mocknet -7. **Restart all services** +1. **Clone the stacks-blockchain-docker repository locally** ```bash -./manage.sh -n -a restart +git clone https://github.com/stacks-network/stacks-blockchain-docker && cd stacks-blockchain-docker ``` -- With optional proxy: +2. **Start the Services** ```bash -./manage.sh -n -a restart -f proxy +./manage.sh -n -a start ``` -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. +:::note With an optional HTTP proxy on port 80: ```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. - +./manage.sh -n -a start -f proxy ``` -9. **Download BNS data to** `./persistent-data/bns-data` - -```bash -./manage.sh bns -``` +::: -10. **Export stacks-blockchain-api events** (_Not applicable for mocknet_) +## **Accessing the services** -```bash -./manage.sh -n -a export -# check logs for completion -./manage.sh -n -a restart -``` +:::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. -11. **Replay stacks-blockchain-api events** (_Not applicable for mocknet_) +Follow the logs to track the sync progress: ```bash -./manage.sh -n -a import -# check logs for completion -./manage.sh -n -a restart +./manage.sh -n -a logs ``` -## **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` +- Ports `20443-20444` are exposed on `localhost` ```bash -curl -sL localhost:20443/v2/info | jq +curl -sL localhost:20443/v2/info | jq -r ``` **stacks-blockchain-api**: -- Port `3999` are exposed to `localhost` +- Port `3999` is exposed on `localhost` ```bash -curl -sL localhost:3999/v2/info | jq +curl -sL localhost:3999 | jq -r ``` **proxy**: -- Port `80` is exposed to `localhost` +- Port `80` is exposed on `localhost` ```bash -curl -sL localhost/v2/info | jq -curl -sL localhost/ | jq +curl -sL localhost/v2/info | jq -r +curl -sL localhost | jq -r ``` --- ## 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 -``` +:::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): ::: --- - -## **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 From 37af59ef0107de122768be8f4a79c371a18563b3 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:47:02 +0100 Subject: [PATCH 0629/1444] New translations index.md (Portuguese, Brazilian) --- .../current/clarity/index.md | 58 +++++++++++++++++++ 1 file changed, 58 insertions(+) create mode 100644 i18n/pt/docusaurus-plugin-content-docs/current/clarity/index.md diff --git a/i18n/pt/docusaurus-plugin-content-docs/current/clarity/index.md b/i18n/pt/docusaurus-plugin-content-docs/current/clarity/index.md new file mode 100644 index 0000000000..903de93a45 --- /dev/null +++ b/i18n/pt/docusaurus-plugin-content-docs/current/clarity/index.md @@ -0,0 +1,58 @@ +--- +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?2 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. If you are unsure what this means, let it not worry you for now. The serious advantage of decidability will become more apparent over time. + +### 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. From eed39592072d412b446ef9fe380425900de79522 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:47:03 +0100 Subject: [PATCH 0630/1444] New translations index.md (Portuguese, Brazilian) --- .../current/stacks-academy/index.md | 11 +++++++++++ 1 file changed, 11 insertions(+) create mode 100644 i18n/pt/docusaurus-plugin-content-docs/current/stacks-academy/index.md diff --git a/i18n/pt/docusaurus-plugin-content-docs/current/stacks-academy/index.md b/i18n/pt/docusaurus-plugin-content-docs/current/stacks-academy/index.md new file mode 100644 index 0000000000..a5bdb3c790 --- /dev/null +++ b/i18n/pt/docusaurus-plugin-content-docs/current/stacks-academy/index.md @@ -0,0 +1,11 @@ +--- +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. From 16066fbb94287f421d63a850f69fcaa259abb1cf Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:47:04 +0100 Subject: [PATCH 0631/1444] New translations proof-of-transfer.md (Portuguese, Brazilian) --- .../stacks-academy/proof-of-transfer.md | 83 +++++++++++++++++++ 1 file changed, 83 insertions(+) create mode 100644 i18n/pt/docusaurus-plugin-content-docs/current/stacks-academy/proof-of-transfer.md diff --git a/i18n/pt/docusaurus-plugin-content-docs/current/stacks-academy/proof-of-transfer.md b/i18n/pt/docusaurus-plugin-content-docs/current/stacks-academy/proof-of-transfer.md new file mode 100644 index 0000000000..50f4b739d6 --- /dev/null +++ b/i18n/pt/docusaurus-plugin-content-docs/current/stacks-academy/proof-of-transfer.md @@ -0,0 +1,83 @@ +--- +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. From c0eb0e70a7a56e1d074712a483f0f71ad495cebb Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:47:04 +0100 Subject: [PATCH 0632/1444] New translations what-is-stacks.md (Portuguese, Brazilian) --- .../current/stacks-academy/what-is-stacks.md | 102 ++++++++++++++++++ 1 file changed, 102 insertions(+) create mode 100644 i18n/pt/docusaurus-plugin-content-docs/current/stacks-academy/what-is-stacks.md diff --git a/i18n/pt/docusaurus-plugin-content-docs/current/stacks-academy/what-is-stacks.md b/i18n/pt/docusaurus-plugin-content-docs/current/stacks-academy/what-is-stacks.md new file mode 100644 index 0000000000..94277da8a9 --- /dev/null +++ b/i18n/pt/docusaurus-plugin-content-docs/current/stacks-academy/what-is-stacks.md @@ -0,0 +1,102 @@ +--- +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. + +There's a lot of jargon, possible assumptions, controversy, and cool technology wrapped up in those statements. So let's get started by getting a 30,000 foot view of what exactly Stacks is. + +## Stacks Explained in (Slightly Less Than) 10 Minutes + +
+ +
+ +## 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, Stacks takes a different approach. + +## 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). + +By taking this 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 with some unique properties, like having its own token, that allow it to maintain a historical ledger of all of its transactions and operate with its own security budget. + +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_. + +Nope. 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. From c450411446444cb73a3f3bacdeb337266d16382a Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:47:05 +0100 Subject: [PATCH 0633/1444] New translations community-tutorials.md (Portuguese, Brazilian) --- .../current/tutorials/community-tutorials.md | 24 +++++++++++++++++++ 1 file changed, 24 insertions(+) create mode 100644 i18n/pt/docusaurus-plugin-content-docs/current/tutorials/community-tutorials.md diff --git a/i18n/pt/docusaurus-plugin-content-docs/current/tutorials/community-tutorials.md b/i18n/pt/docusaurus-plugin-content-docs/current/tutorials/community-tutorials.md new file mode 100644 index 0000000000..a4f3d970ca --- /dev/null +++ b/i18n/pt/docusaurus-plugin-content-docs/current/tutorials/community-tutorials.md @@ -0,0 +1,24 @@ +--- +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/) From 3a85dea4a38fa79954a62e31fd67579ff2743043 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:47:06 +0100 Subject: [PATCH 0634/1444] New translations hello-stacks.md (Portuguese, Brazilian) --- .../current/tutorials/hello-stacks.md | 759 ++++++++++++++++++ 1 file changed, 759 insertions(+) create mode 100644 i18n/pt/docusaurus-plugin-content-docs/current/tutorials/hello-stacks.md diff --git a/i18n/pt/docusaurus-plugin-content-docs/current/tutorials/hello-stacks.md b/i18n/pt/docusaurus-plugin-content-docs/current/tutorials/hello-stacks.md new file mode 100644 index 0000000000..a0a442d135 --- /dev/null +++ b/i18n/pt/docusaurus-plugin-content-docs/current/tutorials/hello-stacks.md @@ -0,0 +1,759 @@ +--- +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. From 478e9ca8e3d90638297b95e281b5159ce291ce7f Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:47:07 +0100 Subject: [PATCH 0635/1444] New translations index.md (Portuguese, Brazilian) --- .../current/tutorials/index.md | 11 +++++++++++ 1 file changed, 11 insertions(+) create mode 100644 i18n/pt/docusaurus-plugin-content-docs/current/tutorials/index.md diff --git a/i18n/pt/docusaurus-plugin-content-docs/current/tutorials/index.md b/i18n/pt/docusaurus-plugin-content-docs/current/tutorials/index.md new file mode 100644 index 0000000000..1d544c7bc1 --- /dev/null +++ b/i18n/pt/docusaurus-plugin-content-docs/current/tutorials/index.md @@ -0,0 +1,11 @@ +--- +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. From 581ae4902ec8b568fccf79dd5680216d12a0b0f5 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:47:08 +0100 Subject: [PATCH 0636/1444] New translations satoshis-ridge.md (Portuguese, Brazilian) --- .../current/tutorials/satoshis-ridge.md | 75 +++++++++++++++++++ 1 file changed, 75 insertions(+) create mode 100644 i18n/pt/docusaurus-plugin-content-docs/current/tutorials/satoshis-ridge.md diff --git a/i18n/pt/docusaurus-plugin-content-docs/current/tutorials/satoshis-ridge.md b/i18n/pt/docusaurus-plugin-content-docs/current/tutorials/satoshis-ridge.md new file mode 100644 index 0000000000..596339ae74 --- /dev/null +++ b/i18n/pt/docusaurus-plugin-content-docs/current/tutorials/satoshis-ridge.md @@ -0,0 +1,75 @@ +--- +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 arguable one of its strengths. + +Instead, we need to create separate layers that add additional functionality without modify 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. From 3f6e6062f1e05f05accf35bdf2d75c7f3348e7aa Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:47:09 +0100 Subject: [PATCH 0637/1444] New translations crash-course.md (Portuguese, Brazilian) --- .../current/clarity/crash-course.md | 122 ++++++++++++++++++ 1 file changed, 122 insertions(+) create mode 100644 i18n/pt/docusaurus-plugin-content-docs/current/clarity/crash-course.md diff --git a/i18n/pt/docusaurus-plugin-content-docs/current/clarity/crash-course.md b/i18n/pt/docusaurus-plugin-content-docs/current/clarity/crash-course.md new file mode 100644 index 0000000000..5b27a3c275 --- /dev/null +++ b/i18n/pt/docusaurus-plugin-content-docs/current/clarity/crash-course.md @@ -0,0 +1,122 @@ +--- +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.md). + +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. + +```clojure +(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: + +```clojure +(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. From 464d2788929efb269fc5a6a3e3d47c06c74e9baf Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:47:10 +0100 Subject: [PATCH 0638/1444] New translations sample-contracts.md (Portuguese, Brazilian) --- .../current/clarity/sample-contracts.md | 14 ++++++++++++++ 1 file changed, 14 insertions(+) create mode 100644 i18n/pt/docusaurus-plugin-content-docs/current/clarity/sample-contracts.md diff --git a/i18n/pt/docusaurus-plugin-content-docs/current/clarity/sample-contracts.md b/i18n/pt/docusaurus-plugin-content-docs/current/clarity/sample-contracts.md new file mode 100644 index 0000000000..adb12a58fd --- /dev/null +++ b/i18n/pt/docusaurus-plugin-content-docs/current/clarity/sample-contracts.md @@ -0,0 +1,14 @@ +--- +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) From 6d96a8329aec14417c32b4522de47e35ebca0283 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:47:10 +0100 Subject: [PATCH 0639/1444] New translations index.md (Portuguese, Brazilian) --- .../current/cookbook/index.md | 64 +++++++++++++++++++ 1 file changed, 64 insertions(+) create mode 100644 i18n/pt/docusaurus-plugin-content-docs/current/cookbook/index.md diff --git a/i18n/pt/docusaurus-plugin-content-docs/current/cookbook/index.md b/i18n/pt/docusaurus-plugin-content-docs/current/cookbook/index.md new file mode 100644 index 0000000000..a2b0e42eea --- /dev/null +++ b/i18n/pt/docusaurus-plugin-content-docs/current/cookbook/index.md @@ -0,0 +1,64 @@ +--- +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 + +Swapping between Bitcoin and Stacks addresses + +Swapping between xBTC and BTC + +Verifying a transaction on the BTC chain + +## 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 + +Airdropping an NFT to a Bitcoin address + +## Stacking and Mining + +Simple stacking pool + +Continuous stacking + +Simple mining pool + +Proof of PoX payout + +## Oracles + +Creating a simple BTC price oracle + +## Frontend + +[Post conditions with Stacks.js](./post-conditions) + +[Authentication with Stacks.js](./stacks-js-auth) + +[Sending transactions with Stacks.js](./stacks-js-sending-transactions) + +## Complete Apps + +[Sup](https://github.com/kenrogers/sup) + +[Hello Stacks](https://github.com/kenrogers/hello-stacks) From 6abd657d715ae093f54bbf94291de2cf41c1fdc5 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:47:11 +0100 Subject: [PATCH 0640/1444] New translations btc-connection.md (Portuguese, Brazilian) --- .../current/stacks-academy/btc-connection.md | 196 ++++++++++++++++++ 1 file changed, 196 insertions(+) create mode 100644 i18n/pt/docusaurus-plugin-content-docs/current/stacks-academy/btc-connection.md diff --git a/i18n/pt/docusaurus-plugin-content-docs/current/stacks-academy/btc-connection.md b/i18n/pt/docusaurus-plugin-content-docs/current/stacks-academy/btc-connection.md new file mode 100644 index 0000000000..b4db915969 --- /dev/null +++ b/i18n/pt/docusaurus-plugin-content-docs/current/stacks-academy/btc-connection.md @@ -0,0 +1,196 @@ +--- +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. + +## Stacks Among Other Bitcoin Layers + +In the [last section](./what-is-stacks.md) we covered what Stacks actually is and what problem it is solving, but this is not a new problem. The Bitcoin write problem has been a bit of a holy grail problem in the crypto world for a while now. + +Bitcoin is the OG cryptocurrency and has the largest market cap, but it also some of the least functionality, which means if we want to make it a productive asset and use it to build a decentralized economy, we need to take a layered approach and let Bitcoin do what it does best, while creating additional layers on top of it to add functionality. + +So how does Stacks compare to some of the other approaches to layering on top of Bitcoin? + +### 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. + +## 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. + +But because it has its own execution environment and smart contract state to maintain, it needs a token to incentivize maintenance of the network. + +But it goes further than that. It is possible to build a system like this without a token using something like merge-mining or a sidechain, but then we lose out on the additional benefit of having the chain state's safety underpinned by its entire token economy's value. + +In the case of Stacks, the safety and liveness of the chain are underpinned by this value, and the stacking mechanism incentivizes network members to increase this value. + +From Jude Nelson, Stacks core developer: + +"How hard is it to cause a safety failure (i.e. a double-spend via a reorg) on just the canonical Stacks chain fork? Anyone can become a miner by spending BTC, so without loss of generality, reverting the last block on the canonical chain is at least as hard in expectation as spending more BTC than the rest of the miners combined for that block. Because each Bitcoin block selects at most one Stacks block, the act of reorging the canonical Stacks chain back N blocks is the act of winning at least N + 1 blocks built off of a common ancestor that is N blocks deep. This is a lower bound on the number of Bitcoin blocks mined during which a reorg needs to take place — in practice, honest miners will keep working on the canonical chain, and will win some Stacks blocks of their own, which in turn increases the number of Stacks blocks the reorging miners must win. + +How costly is it to carry out a reorg of N blocks? It’s a function of how valuable STX is relative to BTC — the more valuable STX are, the more BTC honest miners are committing to mining (this has borne out in practice), and thus the more BTC a reorging miner must commit. Therefore, the cost of a reorg is a function of the value of STX. + +This is similar to the economic security of a PoW blockchain. Like in PoW, each fork of the Stacks chain has its own independent “security budget” — an attacker must out-spend the security budget to carry out a reorg, and the security budget is a function of the block rewards. In PoX, the only difference is that the miners spend another blockchain’s tokens (BTC in Stacks’ case) instead of energy. Therefore, Stacks can’t be a sidechain, a drivechain, or a merge-mined chain, because none of these other systems’ security budgets are a function of their tokens’ worth. Sidechains, drivechains, and merged-mined chains all rely on external miners for their safety, since their safety is guaranteed in part by external miners validating their blocks. The onus on these systems is to get external miners to care enough to do so, and in the case of sidechains, drivechains, and blind merged-mined chains, there is an additional onus to encourage their nodes to mine blocks at all (since there is no on-chain reward for them to earn by doing so). By contrast, disinterested Bitcoin miners neither assist nor prevent a reorg in PoX — they only record the history of all Stacks forks. + +PoX offers two additional, unique security properties on top of PoW. First, no matter how much BTC a reorging miner can commit, the act of executing a reorg is going to be time-consuming. Unless the attacker can attack the Bitcoin chain itself by quickly producing a better Bitcoin fork, a reorging miner must sustain the attack for at least N + 1 Bitcoin blocks. This gives honest miners and users ample time to notice and react to the reorg attempt. + +Second, the history of block production in all Stacks forks is embedded within Bitcoin. This allows the system to leverage Bitcoin’s security budget in order to ensure that all forks are public. This is because the act of producing a hidden Stacks fork, where the fork’s block hashes are not known to the honest miners, is the act of producing a hidden canonical Bitcoin fork. Therefore, the act of producing a hidden Stacks fork is at least as hard as reorging the Bitcoin chain. A PoX chain leverages this property not to prevent reorgs, but to make reorgs unprofitable. + +By anchoring blocks to an existing blockchain, a PoX chain forces reorgs to happen out in the open, thereby giving advance warning to all honest network participants when they happen. Honest miners, users, and exchanges will see the PoX transactions for reorg attempts on the existing blockchain, and adapt their behaviors accordingly: honest miners will increase their commitments, and users and exchanges will require more confirmations for transactions. This makes the act of carrying out a reorg while also making a profit much more challenging, since malicious reorgs — like selfish mining and double-spending — rely on secrecy to work effectively. Specific to Stacks, miners are additionally required to mine for a “warm-up” period of two blocks, during which they must spend BTC at their target commit levels but will not win any Stacks blocks. So, a high-budget reorg attempt will not only be costly, but will also alert the rest of the network before the damage is done." + +- [What Kind of Blockchain is Stacks?](https://stacks.org/stacks-blockchain) + +## 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) From 8eb0039ba7353df670fd75d9d8de3c5b0d868ecd Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:47:12 +0100 Subject: [PATCH 0641/1444] New translations post-conditions.md (Portuguese, Brazilian) --- .../current/stacks-academy/post-conditions.md | 39 +++++++++++++++++++ 1 file changed, 39 insertions(+) create mode 100644 i18n/pt/docusaurus-plugin-content-docs/current/stacks-academy/post-conditions.md diff --git a/i18n/pt/docusaurus-plugin-content-docs/current/stacks-academy/post-conditions.md b/i18n/pt/docusaurus-plugin-content-docs/current/stacks-academy/post-conditions.md new file mode 100644 index 0000000000..bb0727194f --- /dev/null +++ b/i18n/pt/docusaurus-plugin-content-docs/current/stacks-academy/post-conditions.md @@ -0,0 +1,39 @@ +--- +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). From 8e9f180defbb718eda7dc9a7e9c8275f0c99258d Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:47:13 +0100 Subject: [PATCH 0642/1444] New translations creating-an-ft.md (Portuguese, Brazilian) --- .../current/cookbook/creating-an-ft.md | 99 +++++++++++++++++++ 1 file changed, 99 insertions(+) create mode 100644 i18n/pt/docusaurus-plugin-content-docs/current/cookbook/creating-an-ft.md diff --git a/i18n/pt/docusaurus-plugin-content-docs/current/cookbook/creating-an-ft.md b/i18n/pt/docusaurus-plugin-content-docs/current/cookbook/creating-an-ft.md new file mode 100644 index 0000000000..4e3bad99d2 --- /dev/null +++ b/i18n/pt/docusaurus-plugin-content-docs/current/cookbook/creating-an-ft.md @@ -0,0 +1,99 @@ +--- +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) + ) +) +``` From 795a607ffd082cf5a783053fb1364760c92ce218 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:47:14 +0100 Subject: [PATCH 0643/1444] New translations creating-an-nft.md (Portuguese, Brazilian) --- .../current/cookbook/creating-an-nft.md | 87 +++++++++++++++++++ 1 file changed, 87 insertions(+) create mode 100644 i18n/pt/docusaurus-plugin-content-docs/current/cookbook/creating-an-nft.md diff --git a/i18n/pt/docusaurus-plugin-content-docs/current/cookbook/creating-an-nft.md b/i18n/pt/docusaurus-plugin-content-docs/current/cookbook/creating-an-nft.md new file mode 100644 index 0000000000..08faf9393a --- /dev/null +++ b/i18n/pt/docusaurus-plugin-content-docs/current/cookbook/creating-an-nft.md @@ -0,0 +1,87 @@ +--- +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 +Code for this recipe has been pulled from [this NFT tutorial](https://blog.developerdao.com/building-an-nft-with-stacks-and-clarity) from Developer DAO. +::: + +## 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) + ) +) +``` From 285a55120f6373e08e0992e53d9273d529407f64 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:47:14 +0100 Subject: [PATCH 0644/1444] New translations post-conditions.md (Portuguese, Brazilian) --- .../current/cookbook/post-conditions.md | 136 ++++++++++++++++++ 1 file changed, 136 insertions(+) create mode 100644 i18n/pt/docusaurus-plugin-content-docs/current/cookbook/post-conditions.md diff --git a/i18n/pt/docusaurus-plugin-content-docs/current/cookbook/post-conditions.md b/i18n/pt/docusaurus-plugin-content-docs/current/cookbook/post-conditions.md new file mode 100644 index 0000000000..571fc20d48 --- /dev/null +++ b/i18n/pt/docusaurus-plugin-content-docs/current/cookbook/post-conditions.md @@ -0,0 +1,136 @@ +--- +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. From 73aab586f1b45c11b5c03ceca2e7b5d87fcfc089 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:47:15 +0100 Subject: [PATCH 0645/1444] New translations stacks-js-auth.md (Portuguese, Brazilian) --- .../current/cookbook/stacks-js-auth.md | 98 +++++++++++++++++++ 1 file changed, 98 insertions(+) create mode 100644 i18n/pt/docusaurus-plugin-content-docs/current/cookbook/stacks-js-auth.md diff --git a/i18n/pt/docusaurus-plugin-content-docs/current/cookbook/stacks-js-auth.md b/i18n/pt/docusaurus-plugin-content-docs/current/cookbook/stacks-js-auth.md new file mode 100644 index 0000000000..89d1f06e00 --- /dev/null +++ b/i18n/pt/docusaurus-plugin-content-docs/current/cookbook/stacks-js-auth.md @@ -0,0 +1,98 @@ +--- +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 && ( + + ); +} +``` From 0653cfa28be2782f8b84b929916936d596693e6d Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:47:16 +0100 Subject: [PATCH 0646/1444] New translations stacks-js-sending-transactions.md (Portuguese, Brazilian) --- .../stacks-js-sending-transactions.md | 55 +++++++++++++++++++ 1 file changed, 55 insertions(+) create mode 100644 i18n/pt/docusaurus-plugin-content-docs/current/cookbook/stacks-js-sending-transactions.md diff --git a/i18n/pt/docusaurus-plugin-content-docs/current/cookbook/stacks-js-sending-transactions.md b/i18n/pt/docusaurus-plugin-content-docs/current/cookbook/stacks-js-sending-transactions.md new file mode 100644 index 0000000000..849c7d1f42 --- /dev/null +++ b/i18n/pt/docusaurus-plugin-content-docs/current/cookbook/stacks-js-sending-transactions.md @@ -0,0 +1,55 @@ +--- +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. From 7e07fa0cb5aaedc5f46e4683ac16c136868c4405 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:47:17 +0100 Subject: [PATCH 0647/1444] New translations _category_.json (Portuguese, Brazilian) --- .../current/clarity/noteworthy-contracts/_category_.json | 8 ++++++++ 1 file changed, 8 insertions(+) create mode 100644 i18n/pt/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/_category_.json diff --git a/i18n/pt/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/_category_.json b/i18n/pt/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/_category_.json new file mode 100644 index 0000000000..f5de305558 --- /dev/null +++ b/i18n/pt/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/_category_.json @@ -0,0 +1,8 @@ +{ + "label": "Noteworthy Contracts", + "position": 4, + "link": { + "type": "generated-index", + "description": "Specific deployed Clarity Contracts worth mentioning." + } +} \ No newline at end of file From 8883af4b68fca6b685591886b0468aadcc00c78e Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:47:18 +0100 Subject: [PATCH 0648/1444] New translations bns-contract.md (Portuguese, Brazilian) --- .../noteworthy-contracts/bns-contract.md | 519 ++++++++++++++++++ 1 file changed, 519 insertions(+) create mode 100644 i18n/pt/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/bns-contract.md diff --git a/i18n/pt/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/bns-contract.md b/i18n/pt/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/bns-contract.md new file mode 100644 index 0000000000..a7770b7d24 --- /dev/null +++ b/i18n/pt/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/bns-contract.md @@ -0,0 +1,519 @@ +--- +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 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` From ffa4ac7e1ee529a6f8ba1802b63624e180c91134 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:47:19 +0100 Subject: [PATCH 0649/1444] New translations xbtc.md (Portuguese, Brazilian) --- .../clarity/noteworthy-contracts/xbtc.md | 28 +++++++++++++++++++ 1 file changed, 28 insertions(+) create mode 100644 i18n/pt/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/xbtc.md diff --git a/i18n/pt/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/xbtc.md b/i18n/pt/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/xbtc.md new file mode 100644 index 0000000000..e535dcf260 --- /dev/null +++ b/i18n/pt/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/xbtc.md @@ -0,0 +1,28 @@ +--- +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) From 178562115c63f57717711005dc7d451e064d6f15 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:47:20 +0100 Subject: [PATCH 0650/1444] New translations index.md (Portuguese, Brazilian) --- .../current/glossary/index.md | 284 ++++++++++++++++++ 1 file changed, 284 insertions(+) create mode 100644 i18n/pt/docusaurus-plugin-content-docs/current/glossary/index.md diff --git a/i18n/pt/docusaurus-plugin-content-docs/current/glossary/index.md b/i18n/pt/docusaurus-plugin-content-docs/current/glossary/index.md new file mode 100644 index 0000000000..419c0e0d73 --- /dev/null +++ b/i18n/pt/docusaurus-plugin-content-docs/current/glossary/index.md @@ -0,0 +1,284 @@ +--- +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. From f6df5d370d3495d97dd08bcf7a75a4e444396126 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:47:20 +0100 Subject: [PATCH 0651/1444] New translations quicknode.md (Portuguese, Brazilian) --- .../current/nodes-and-miners/quicknode.md | 45 +++++++++++++++++++ 1 file changed, 45 insertions(+) create mode 100644 i18n/pt/docusaurus-plugin-content-docs/current/nodes-and-miners/quicknode.md diff --git a/i18n/pt/docusaurus-plugin-content-docs/current/nodes-and-miners/quicknode.md b/i18n/pt/docusaurus-plugin-content-docs/current/nodes-and-miners/quicknode.md new file mode 100644 index 0000000000..1281964689 --- /dev/null +++ b/i18n/pt/docusaurus-plugin-content-docs/current/nodes-and-miners/quicknode.md @@ -0,0 +1,45 @@ +--- +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. From afd4b82cfbbe31933e28d50d1ecaa920cd401c10 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:47:21 +0100 Subject: [PATCH 0652/1444] New translations defi.md (Portuguese, Brazilian) --- .../current/services-using-stacks/defi.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) 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 index 51defacba7..58717a3234 100644 --- 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 @@ -26,7 +26,7 @@ Please edit this page to add any relevant new site that we are missing. ## Lnswap -[LNSWAP](https://www.lnswap.org). Non custiodial crypto currency exchange +[LNSWAP](https://www.lnswap.org). Non-custodial crypto currency exchange ![](/img/sh_lnswap.png) @@ -41,4 +41,3 @@ Please edit this page to add any relevant new site that we are missing. [Stackswap](https://app.stackswap.org/v2) ![](/img/sh_stackswap.png) - From 69f92d21c2f501f44beb91571cd64c2ad66a0071 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:47:22 +0100 Subject: [PATCH 0653/1444] New translations more.md (Portuguese, Brazilian) --- .../current/services-using-stacks/more.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) 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 index df0b3e2254..1e14b9a5a5 100644 --- 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 @@ -18,6 +18,6 @@ Please edit this page to add any relevant new site that we are missing. ## Sigle -[Sigle](https://www.sigle.io/) is a decentralised and open source web 3 writing platform. +[Sigle](https://www.sigle.io/) is a decentralized and open source web 3 writing platform. -![](/img/sh_sigle.png) \ No newline at end of file +![](/img/sh_sigle.png) From 9472905dfe40085702bcc4fe18126442c1b7eb29 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:47:23 +0100 Subject: [PATCH 0654/1444] New translations nft.md (Portuguese, Brazilian) --- .../current/services-using-stacks/nft.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) 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 index abb770663c..d582604854 100644 --- 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 @@ -15,6 +15,7 @@ Please edit this page to add any relevant new site that we are missing. ![website-screenshot](/img/sh_nft_byzantion.png) ### [Gamma](https://gamma.io/) + ![website-screenshot](/img/sh_nft_gamma.png) ### [Megapont](https://www.megapont.com/) @@ -35,4 +36,4 @@ Please edit this page to add any relevant new site that we are missing. ### [Superfandom](https://superfandom.io/) -![website-screenshot](/img/sh_superfandom.png) \ No newline at end of file +![website-screenshot](/img/sh_superfandom.png) From b3ff3441ebd708847628a5438a26e2682de8f166 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:47:24 +0100 Subject: [PATCH 0655/1444] New translations stacks-info-sites.md (Portuguese, Brazilian) --- .../current/services-using-stacks/stacks-info-sites.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) 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 index 35ced8dac6..54f6823e33 100644 --- 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 @@ -30,7 +30,7 @@ Please edit this page to add any relevant new site that we are missing. ![website-screenshot](/img/sh_stxstats.png) -### [Novuminsights](https://stacks.novuminsights.com/health) +### [Novum Insights](https://stacks.novuminsights.com/health) ![website-screenshot](/img/sh_novuminsights.png) From dceb409eea4e58f2992949a707019cf0437bd72e Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:47:25 +0100 Subject: [PATCH 0656/1444] New translations wallets.md (Portuguese, Brazilian) --- .../current/services-using-stacks/wallets.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) 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 index e5ea6c5b45..2d3fcc85f2 100644 --- 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 @@ -15,6 +15,7 @@ Please edit this page to add any relevant new site that we are missing. [Blockchain.com](https://www.blockchain.com/wallet) ![](/img/sh_blockchain.png) + ## Boom [Boom](https://boom.money) @@ -26,6 +27,7 @@ Please edit this page to add any relevant new site that we are missing. [D'CENT](https://dcentwallet.com) ![](/img/sh_dcent.png) + ## Hiro Wallet [Hiro Wallet](https://www.hiro.so/wallet) @@ -48,4 +50,4 @@ Please edit this page to add any relevant new site that we are missing. [Wise](https://wiseapp.id) -![](/img/sh_wiseapp.png) \ No newline at end of file +![](/img/sh_wiseapp.png) From 187859fa5d39c0783ffbce9bfe532be88a6394ec Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:47:25 +0100 Subject: [PATCH 0657/1444] New translations whitepapers.md (Portuguese, Brazilian) --- .../current/stacks-academy/whitepapers.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) create mode 100644 i18n/pt/docusaurus-plugin-content-docs/current/stacks-academy/whitepapers.md diff --git a/i18n/pt/docusaurus-plugin-content-docs/current/stacks-academy/whitepapers.md b/i18n/pt/docusaurus-plugin-content-docs/current/stacks-academy/whitepapers.md new file mode 100644 index 0000000000..0e564fbf44 --- /dev/null +++ b/i18n/pt/docusaurus-plugin-content-docs/current/stacks-academy/whitepapers.md @@ -0,0 +1,12 @@ +--- +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) From 9944a2fe604864ba3a282fea738280cb53f71d39 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:47:26 +0100 Subject: [PATCH 0658/1444] New translations stacking-contract.md (Portuguese, Brazilian) --- .../noteworthy-contracts/stacking-contract.md | 352 ++++++++++++++++++ 1 file changed, 352 insertions(+) create mode 100644 i18n/pt/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/stacking-contract.md diff --git a/i18n/pt/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/stacking-contract.md b/i18n/pt/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/stacking-contract.md new file mode 100644 index 0000000000..c0027256cd --- /dev/null +++ b/i18n/pt/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/stacking-contract.md @@ -0,0 +1,352 @@ +--- +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. 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` From f650b69c0da1c053ab719231c98a4ab5019c1aac Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:47:27 +0100 Subject: [PATCH 0659/1444] New translations index.md (Portuguese, Brazilian) --- .../current/next-steps/index.md | 39 +++++++++++++++++++ 1 file changed, 39 insertions(+) create mode 100644 i18n/pt/docusaurus-plugin-content-docs/current/next-steps/index.md diff --git a/i18n/pt/docusaurus-plugin-content-docs/current/next-steps/index.md b/i18n/pt/docusaurus-plugin-content-docs/current/next-steps/index.md new file mode 100644 index 0000000000..00ddec9178 --- /dev/null +++ b/i18n/pt/docusaurus-plugin-content-docs/current/next-steps/index.md @@ -0,0 +1,39 @@ +--- +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) From f7a04b07d88bb5cb7dbc06f568232f5f54ce67ab Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:47:28 +0100 Subject: [PATCH 0660/1444] New translations sips.md (Portuguese, Brazilian) --- .../current/stacks-academy/sips.md | 52 +++++++++++++++++++ 1 file changed, 52 insertions(+) create mode 100644 i18n/pt/docusaurus-plugin-content-docs/current/stacks-academy/sips.md diff --git a/i18n/pt/docusaurus-plugin-content-docs/current/stacks-academy/sips.md b/i18n/pt/docusaurus-plugin-content-docs/current/stacks-academy/sips.md new file mode 100644 index 0000000000..aa2db18e62 --- /dev/null +++ b/i18n/pt/docusaurus-plugin-content-docs/current/stacks-academy/sips.md @@ -0,0 +1,52 @@ +--- +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/IJ15791776) 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-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. From d0a3cb41bf8b152c88c8db46a5f353a891a047b5 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:47:29 +0100 Subject: [PATCH 0661/1444] New translations hosted-nodes.md (Portuguese, Brazilian) --- .../current/nodes-and-miners/hosted-nodes.md | 25 +++++++++++++++++++ 1 file changed, 25 insertions(+) create mode 100644 i18n/pt/docusaurus-plugin-content-docs/current/nodes-and-miners/hosted-nodes.md diff --git a/i18n/pt/docusaurus-plugin-content-docs/current/nodes-and-miners/hosted-nodes.md b/i18n/pt/docusaurus-plugin-content-docs/current/nodes-and-miners/hosted-nodes.md new file mode 100644 index 0000000000..12d86c7ee2 --- /dev/null +++ b/i18n/pt/docusaurus-plugin-content-docs/current/nodes-and-miners/hosted-nodes.md @@ -0,0 +1,25 @@ +--- +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. From 4c8b3ea4fc253f5c0c5dcb4480581a3d366d738a Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:47:30 +0100 Subject: [PATCH 0662/1444] New translations authentication.md (Indonesian) --- .../current/stacks-academy/authentication.md | 63 +++++++++++++++++++ 1 file changed, 63 insertions(+) create mode 100644 i18n/id/docusaurus-plugin-content-docs/current/stacks-academy/authentication.md diff --git a/i18n/id/docusaurus-plugin-content-docs/current/stacks-academy/authentication.md b/i18n/id/docusaurus-plugin-content-docs/current/stacks-academy/authentication.md new file mode 100644 index 0000000000..1a03fbdc35 --- /dev/null +++ b/i18n/id/docusaurus-plugin-content-docs/current/stacks-academy/authentication.md @@ -0,0 +1,63 @@ +--- +title: Autentikasi +description: Daftar dan masuk pengguna menggunakan identitas pada blockchain Stacks +sidebar_position: 8 +--- + +## 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. From 3a1eeb7c8206ddc4311c11fb06e166e69caa0bb3 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:47:31 +0100 Subject: [PATCH 0663/1444] New translations bns.md (Indonesian) --- .../current/stacks-academy/bns.md | 241 ++++++++++++++++++ 1 file changed, 241 insertions(+) create mode 100644 i18n/id/docusaurus-plugin-content-docs/current/stacks-academy/bns.md diff --git a/i18n/id/docusaurus-plugin-content-docs/current/stacks-academy/bns.md b/i18n/id/docusaurus-plugin-content-docs/current/stacks-academy/bns.md new file mode 100644 index 0000000000..c9c8ac533a --- /dev/null +++ b/i18n/id/docusaurus-plugin-content-docs/current/stacks-academy/bns.md @@ -0,0 +1,241 @@ +--- +title: Sistem Penamaan Blockchain +description: Mengikat nama pengguna Stacks ke status luar-rantai +sidebar_position: 8 +--- + +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. 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). + +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). From e2ed33b043285bc4ec2d19a74919fc14d79b58cb Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:47:32 +0100 Subject: [PATCH 0664/1444] New translations docs.md (Indonesian) --- .../current/contribute/docs.md | 24 ++++++++++++------- 1 file changed, 15 insertions(+), 9 deletions(-) diff --git a/i18n/id/docusaurus-plugin-content-docs/current/contribute/docs.md b/i18n/id/docusaurus-plugin-content-docs/current/contribute/docs.md index d177a03b4a..cc6a3747f0 100644 --- a/i18n/id/docusaurus-plugin-content-docs/current/contribute/docs.md +++ b/i18n/id/docusaurus-plugin-content-docs/current/contribute/docs.md @@ -7,7 +7,7 @@ description: Learn how this site is built, and how you can contribute to it. 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). +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/). @@ -15,7 +15,7 @@ Don't want to learn it? No need to. Write [in plain text an issue on Github](htt :::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 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). @@ -24,28 +24,32 @@ To add new content, they are two different ways to do it, the [easy way](#easy-w [**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. +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 yourhanges in real time. + - `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. -## Aditional information +## 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 ``` @@ -54,8 +58,8 @@ Before running this command for the first time you will need to run `npm install 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 ``` @@ -91,7 +95,7 @@ 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. +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 @@ -124,6 +128,7 @@ And execute prettier with the following command: npx prettier --write mynewfiletocheck.md ``` --> + ### 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. @@ -138,6 +143,7 @@ To write a code block, you need to wrap your code in ` ```language `, and end yo (define-public (get-counter) (ok (var-get counter))) ``` + ### Admonitions You can use the following admonitions to highlight content. @@ -204,4 +210,4 @@ Some **content** with _markdown_ `syntax`. Some **content** with _markdown_ `syntax`. -::: \ No newline at end of file +::: From 6e3e48fcb543d03a2fba9998b57e4e943ef8050f Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:47:33 +0100 Subject: [PATCH 0665/1444] New translations translations.md (Indonesian) --- .../current/contribute/translations.md | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/i18n/id/docusaurus-plugin-content-docs/current/contribute/translations.md b/i18n/id/docusaurus-plugin-content-docs/current/contribute/translations.md index 04cc3c5f7c..98128b0d99 100644 --- a/i18n/id/docusaurus-plugin-content-docs/current/contribute/translations.md +++ b/i18n/id/docusaurus-plugin-content-docs/current/contribute/translations.md @@ -1,25 +1,24 @@ --- title: Contribute with translations -description: Want to help tranlating these docs to your local language? +description: Want to help translating 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. +Translations are managed with Crowdin. Anybody can collaborate and no technical 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. +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 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 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) From 57eef2f2894b88556b9d774197de9364d76f5063 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:47:35 +0100 Subject: [PATCH 0666/1444] New translations gaia-on-ec2.md (Indonesian) --- .../current/gaia/gaia-on-ec2.md | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) 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 index 1653a061ac..7e25e57bc7 100644 --- 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 @@ -26,9 +26,10 @@ Use a link in the table to launch the [CloudFormation](https://console.aws.amazo ### Step 2 - Setup stack using template -You need to configure the template with the appropiate values for your hub and domain it runs on. +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 ``` @@ -52,7 +53,7 @@ Specify the stack details and then click `Next`: ![Specify template](/img/cloudf | 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`. | +| 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 | @@ -93,7 +94,9 @@ ssh -i admin@ 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 +![](/img/cloudformation-gaia-template1-designer.png) From 89e1345df1f7e9cf797c7f8a523779a8d5c63a6b Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:47:36 +0100 Subject: [PATCH 0667/1444] New translations gaia.md (Indonesian) --- .../current/gaia/gaia.md | 12 +++++++++--- 1 file changed, 9 insertions(+), 3 deletions(-) diff --git a/i18n/id/docusaurus-plugin-content-docs/current/gaia/gaia.md b/i18n/id/docusaurus-plugin-content-docs/current/gaia/gaia.md index af9898274b..21d7ca8705 100644 --- a/i18n/id/docusaurus-plugin-content-docs/current/gaia/gaia.md +++ b/i18n/id/docusaurus-plugin-content-docs/current/gaia/gaia.md @@ -1,14 +1,20 @@ --- title: Gaia description: Arsitektur penyimpanan terdesentralisasi untuk data luar-rantai -sidebar_position: 5 +sidebar_position: 6 tags: - gaia --- ## Pengantar -Aplikasi yang dibuat dengan blockchain Stacks menyimpan data luar-rantai menggunakan sistem penyimpanan yang disebut Gaia. +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. Sementara metadata transaksional publik paling baik disimpan di blockchain Stacks, data aplikasi pengguna seringkali dapat disimpan lebih efisien dan pribadi di penyimpanan Gaia. @@ -38,7 +44,7 @@ Blockchain Stacks hanya menyimpan data identitas. Data yang dibuat oleh tindakan 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) +![Gai storage](/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. From 0aa145fc2a43ffed0ea24ee827c9389530a95b2f Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:47:37 +0100 Subject: [PATCH 0668/1444] New translations setup-linux.md (Indonesian) --- .../current/gaia/setup-linux.md | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) 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 index db427f890a..2c0ca2b92e 100644 --- a/i18n/id/docusaurus-plugin-content-docs/current/gaia/setup-linux.md +++ b/i18n/id/docusaurus-plugin-content-docs/current/gaia/setup-linux.md @@ -1,6 +1,6 @@ --- 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. +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 @@ -19,8 +19,7 @@ This configuration will setup the following 4 docker containers: 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: +**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 @@ -48,8 +47,7 @@ chmod +x ${DESTINATION_DC}/docker-compose 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. +**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 From 66dc8aa6f472dab542a8b811f6a8d466e9b298c2 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:47:38 +0100 Subject: [PATCH 0669/1444] New translations digitalocean.md (Indonesian) --- .../current/nodes-and-miners/digitalocean.md | 41 +++++++++++-------- 1 file changed, 25 insertions(+), 16 deletions(-) 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 index 07e71136e4..baf4178b5a 100644 --- 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 @@ -1,28 +1,30 @@ --- -title: Stacks di DigitalOcean +title: Run a Node with Digital Ocean description: A guide to setup Stacks on DigitalOcean -sidebar_position: 4 +sidebar_position: 2 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). +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`. +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 plan that meets the minimum requirements) and your prefered datacenter region. ![](/img/sh_digitalocean-choose-plan.png) +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 if your prefer. +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) @@ -46,41 +48,48 @@ Congratulations! You are now running the Stacks Blockchain. You can click on `Co ## 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). +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`. -Once the stacks blockchain starts to sync with peers, application ports will open and nginx port 80 will now start proxying requests. +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 v3.0.3 (master:cd0c8aef)", + "server_version": "stacks-blockchain-api v6.2.3 (master:77ab3ae2)", "status": "ready", "chain_tip": { - "block_height": 16220, - "block_hash": "0x3123fba9c0de6b569573494cf83c1d5d198a66bfd5f48ef97949b6bf11ba13be", - "index_block_hash": "0xeec960fbbd6186b4ccac85ce12adba72be497d881f81e077305c90955b51a6ae" + "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/README.md#quickstart). +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). -## API Creation +## 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 -curl -X POST -H 'Content-Type: application/json' \ +$ export TOKEN= +$ 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"}' \ + '{"name":"stacks-blockchain","region":"sfo2","size":"s-2vcpu-4gb","image":"stacksfoundation-stacksblockchain"}' \ "https://api.digitalocean.com/v2/droplets" ``` From c5333a460404a47294bfae4d3fadec5f99f63f57 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:47:40 +0100 Subject: [PATCH 0670/1444] New translations index.md (Indonesian) --- .../current/nodes-and-miners/index.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) 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 index 979265d7b2..f5b5ba791a 100644 --- 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 @@ -1,11 +1,11 @@ --- title: Noda dan Penambang description: Noda dan Penambang -sidebar_position: 7 +sidebar_position: 5 --- -Berikut adalah semua langkah untuk menjalankan noda dan penambang, baik di mainnet maupun testnet. +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. -## Apa itu noda Stacks? +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. -## Apa itu penambang Stacks? +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. From fcfb3ecece7fe712791220a28232b3eb2bed66f5 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:47:41 +0100 Subject: [PATCH 0671/1444] New translations miner-mainnet.md (Indonesian) --- .../current/nodes-and-miners/miner-mainnet.md | 301 +++++++----------- 1 file changed, 110 insertions(+), 191 deletions(-) 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 index 499abebafe..822580c447 100644 --- 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 @@ -1,166 +1,100 @@ --- title: Menambang token Stacks mainnet -description: Menyiapkan dan menjalankan penambang di mainnet Stacks 2.0 -sidebar_position: 5 +description: Set up and run a miner on Stacks Mainnet +sidebar_position: 6 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. +For more on the technical details of mining, please review the [mining guide](../stacks-academy/mining) -If you're interested in mining on the testnet, you can find instructions on how to do that [here](miner-testnet): +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 want to learn more about the technical details of mining, please review the [mining guide](../understand-stacks/mining): +If you're interested in mining on the Stacks testnet, you can find instructions on how to do that [here](miner-testnet): -## Menjalankan bitcoind secara lokal +## Running a Bitcoin Mainnet Full Node -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) +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. -Pertama, unduh perangkat lunak bitcoind untuk platform Anda dari https://bitcoin.org/en/download. +- [Ensure your computer meets the minimum hardware requirements before continuing.](https://bitcoin.org/en/bitcoin-core/features/requirements#system-requirements) -Selanjutnya, mulai bitcoind dengan konfigurasi berikut: +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): -```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 -``` +:::tip It is recommened to use a persistent location for the chainstate, in the steps below we're using `/bitcoin` ::: -Terakhir, mulai bitcoind sebagai berikut: +### Update the Bitcoin Configuration File -```bash -bitcoind -conf=path/to/bitcoin.conf -``` - -Mungkin perlu waktu beberapa hari hingga noda tersebut disinkronkan dengan mainnet Bitcoin. +Next, update the bitcoin configuration: -## 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: +- **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 -[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 = "" -... +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 ``` -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. +### Start Bitcoin -Untuk menjalankan penambang Anda, jalankan ini di baris perintah: +Finally, start bitcoin as follows (adjust the `conf` path to where it was created in the previous step, i.e. `$HOME/bitcoin.conf`): ```bash -stacks-node start --config=./testnet/stacks-node/conf/mainnet-miner-conf.toml +bitcoind -conf=$HOME/bitcoin.conf ``` -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 -``` +:::note +It will take a few days for the node to synchronize with Bitcoin mainnet. +::: -Kode di atas akan mengkompilasi biner yang dioptimalkan. Untuk menggunakannya, jalankan: +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 -cd ../.. -./target/release/stacks-node start --config=./mainnet-miner-conf.toml +$ bitcoin-cli \ + -rpcconnect=localhost \ + -rpcport=8332 \ + -rpcuser=btcuser \ + -rpcpassword=btcpassword \ +getblockchaininfo | jq .blocks +773281 ``` -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 -``` +## Running a Stacks Blockchain miner -## Menjalankan penambang di Windows +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) -### Prasyarat +_There may be some extra requirements to building, [defined here](https://github.com/stacksfoundation/miner-docs/blob/main/prerequisites.md#install-required-packages)_ -Make sure are [running a node](run-a-node) and [running bitcoind locally](#running-bitcoind-locally) before starting this tutorial. +:::tip It is recommened to use a persistent location for the chainstate, in the steps below we're using `/stacks-blockchain` ::: -### Membuat keychain dan mendapatkan token mainnet di Windows +### Generate a keychain -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. +Pertama, sebuah keychain perlu dibuat. With this keychain, we'll purchase some BTC from a cryptocurrency exchange, and then use that BTC to start mining. -Untuk mendapatkan keychain, cara paling sederhana adalah dengan menggunakan `stacks-cli`. Kita akan menggunakan perintah `stx make-keychain`. - -Membuat keychain: +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 -npm install --global @stacks/cli -stx make_keychain > cli_keychain.json -type cli_keychain.json +npx @stacks/cli make_keychain 2>/dev/null | jq -r ``` -Setelah ini berjalan, Anda mungkin akan melihat beberapa log instalasi, dan pada akhirnya Anda akan melihat beberapa JSON yang terlihat seperti ini: +After this runs, you should see some JSON printed to the screen that looks like this: ```json { @@ -174,109 +108,99 @@ Setelah ini berjalan, Anda mungkin akan melihat beberapa log instalasi, dan pada } ``` -:::tip Check out the [Stacks CLI reference](https://docs.hiro.so/references/stacks-cli) for more details ::: +:::warning **Do not lose this information** - we'll need to use the `privateKey` and `btcAddress` fields in later steps. ::: -Alamat BTC di atas kemudian perlu diimpor ke jaringan BTC. +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=your-user -rpcpassword=your-password importaddress +bitcoin-cli \ + -rpcport=8332 \ + -rpcuser=btcuser \ + -rpcpassword=btcpassword \ +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 + + +### Update the Stacks Blockchain Configuration File -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). +Sekarang, kita perlu mengkonfigurasi noda kita untuk menggunakan keychain Bitcoin ini. 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`. -Perbarui properti berikut: +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. Simpan dan tutup file konfigurasi ini. + +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] -... -# Masukkan kunci privat Anda di sini -seed = "replace-with-your-private-key" -local_peer_seed = "replace-with-your-private-key" -... +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] -... -# To mine on mainnet, you need to run bitcoind locally -# Details can be found in above section, 'Running bitcoind locally' +chain = "bitcoin" +mode = "mainnet" peer_host = "127.0.0.1" -username = "" -password = "" -... +username = "" +password = "" +rpc_port = 8332 +peer_port = 8333 +satoshis_per_byte = 100 +burn_fee_cap = 20000 ``` -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 +### Start the Stacks Blockchain -Untuk memulai penambang Anda, jalankan ini di baris perintah: +Untuk menjalankan penambang Anda, jalankan ini di baris perintah: ```bash -stacks-node start --config=testnet/stacks-node/conf/mainnet-miner-conf.toml +stacks-node start --config=$HOME/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 +### Enable Debug Logging 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 +STACKS_LOG_DEBUG=1 stacks-node start --config=$HOME/mainnet-miner-conf.toml ``` -## Opsional: Berjalan dengan Docker +--- + +## Optional: Running a Stacks Blockchain miner with Docker -Atau, Anda dapat menjalankan noda mainnet dengan Docker. +Alternatively, you can run a Stacks mainnet miner with Docker. -:::caution Ensure you have [Docker](https://docs.docker.com/get-docker/) installed on your machine. ::: +:::caution Ensure you have [Docker](https://docs.docker.com/get-docker/) installed. ::: -### Membuat keychain dan mendapatkan token +### Generate a Keychain and Get Some Tokens Membuat keychain: ```bash -docker run -i node:14-alpine npx @stacks/cli make_keychain 2>/dev/null +docker run -i node:14-alpine npx @stacks/cli make_keychain 2>/dev/null | jq -r ``` -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: +Kita perlu mendapatkan beberapa BTC ke alamat tersebut. 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). -```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 = "" -... -``` +### Update Stacks Blockchain Docker Configuration File -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. +Use the steps oulined above to create the [configuration file](miner-mainnet#update-the-stacks-blockchain-configuration-file) -### Memulai penambang +### 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 ::: @@ -287,7 +211,8 @@ docker run -d \ --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" \ + -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 \ @@ -302,9 +227,9 @@ 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). +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). -Pastikan Anda telah menginstal prasyarat berikut di mesin Anda: +Ensure you have the following prerequisites installed: - [Docker](https://docs.docker.com/get-docker/) - [minikube](https://minikube.sigs.k8s.io/docs/start/) (Hanya diperlukan jika membuat klaster Kubernetes lokal) @@ -313,13 +238,7 @@ Pastikan Anda telah menginstal prasyarat berikut di mesin Anda: ### 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). +Use the steps [outlined above](miner-mainnet#generate-a-keychain-and-get-some-tokens) ### Instal grafik dan jalankan penambang From 7a73311d406956813556fd8dd1193727cd3bbac1 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:47:41 +0100 Subject: [PATCH 0672/1444] New translations miner-testnet.md (Indonesian) --- .../current/nodes-and-miners/miner-testnet.md | 318 +++++++----------- 1 file changed, 130 insertions(+), 188 deletions(-) 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 index e892bf9c82..70e843114b 100644 --- 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 @@ -1,35 +1,52 @@ --- title: Menambang token Stacks testnet -description: Menyiapkan dan menjalankan penambang di testnet Stacks 2.0 -sidebar_position: 4 +description: Set up and run a miner on Stacks Testnet +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 testnet. +For more on the technical details of mining, please review the [mining guide](../stacks-academy/mining) -If you want to learn more about the technical details of mining, please review the [mining guide](../understand-stacks/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)). -## Menjalankan bitcoind secara lokal +If you're interested in mining on the Stacks mainnet, you can find instructions on how to do that [here](miner-mainnet): -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) +## Running a Bitcoin Testnet Full Node -Pertama, unduh perangkat lunak bitcoind untuk platform Anda dari https://bitcoin.org/en/download. +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. -Selanjutnya, mulai bitcoind dengan konfigurasi berikut: +- [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 -rpcuser=your-bitcoind-username -rpcpassword=your-bitcoind-password testnet=1 -txindex=0 -listen=1 -rpcserialversion=0 -maxorphantx=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 @@ -37,126 +54,51 @@ 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" -... +### Start Bitcoin -[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: +Terakhir, mulai bitcoind sebagai berikut: ```bash -stacks-node start --config=./testnet/stacks-node/conf/testnet-miner-conf.toml +bitcoind -conf=$HOME/bitcoin.conf ``` -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 -``` +:::note +It will take a few hours for the node to synchronize with Bitcoin testnet. +::: -Kode di atas akan mengkompilasi biner yang dioptimalkan. Untuk menggunakannya, jalankan: +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 -cd ../.. -./target/release/stacks-node start --config=./testnet/conf/testnet-follower-conf.toml +$ bitcoin-cli \ + -rpcconnect=localhost \ + -rpcport=18332 \ + -rpcuser=btcuser \ + -rpcpassword=btcpass \ +getblockchaininfo | jq .blocks +2417570 ``` -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 +## Running a Stacks Blockchain miner -### Prasyarat +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) -Make sure are [running a testnet node](run-a-node) before starting this tutorial. +_There may be some extra requirements to building, [defined here](https://github.com/stacksfoundation/miner-docs/blob/main/prerequisites.md#install-required-packages)_ -### Membuat keychain dan mendapatkan token testnet di Windows +:::tip It is recommened to use a persistent location for the chainstate, in the steps below we're using `/stacks-blockchain` ::: -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. +### Generate a keychain -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. +Pertama, sebuah keychain perlu dibuat. Dengan keychain ini, kita akan mendapatkan beberapa BTC testnet dari faucet, dan kemudian menggunakan BTC tersebut untuk mulai menambang. -Membuat keychain: +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 -npm install --global @stacks/cli -stx make_keychain -t > cli_keychain.json -type cli_keychain.json +npx @stacks/cli make_keychain -t 2>/dev/null | jq -r ``` -Setelah ini berjalan, Anda mungkin akan melihat beberapa log instalasi, dan pada akhirnya Anda akan melihat beberapa JSON yang terlihat seperti ini: +After this runs, you should see some JSON printed to the screen that looks like this: ```json { @@ -170,107 +112,110 @@ Setelah ini berjalan, Anda mungkin akan melihat beberapa log instalasi, dan pada } ``` -:::tip Check out the [Stacks CLI reference](https://docs.hiro.so/references/stacks-cli) for more details ::: +:::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 +``` + +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. -Meminta BTC dari faucet: +### Update the Stacks Blockchain Configuration File -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. 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`. -### Perbarui file konfigurasi +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. Simpan dan tutup file konfigurasi ini. -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). +Next, update the bitcoin configuration: -Perbarui properti berikut: +- **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] -... -seed = "replace-with-your-private-key" -local_peer_seed = "replace-with-your-private-key" -... +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] -... -# To mine on Testnet, you need to run bitcoind locally -# Details can be found in above section, 'Running bitcoind locally' +chain = "bitcoin" +mode = "xenon" peer_host = "127.0.0.1" -username = "" -password = "" -... +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 ``` -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 +### Start the Stacks Blockchain -Untuk memulai penambang Anda, jalankan ini di baris perintah: +Untuk menjalankan penambang Anda, jalankan ini di baris perintah: ```bash -stacks-node start --config=testnet/stacks-node/conf/testnet-miner-conf.toml +stacks-node start --config=$HOME/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 +### Enable Debug Logging 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 +STACKS_LOG_DEBUG=1 stacks-node start --config=$HOME/testnet-miner-conf.toml ``` -## Opsional: Berjalan dengan Docker +--- + +## Optional: Running a Stacks Blockchain miner with Docker -Atau, Anda dapat menjalankan noda testnet dengan Docker. +Alternatively, you can run a Stacks testnet miner with Docker. -:::warning Ensure you have [Docker](https://docs.docker.com/get-docker/) installed on your machine. ::: +:::caution Ensure you have [Docker](https://docs.docker.com/get-docker/) installed ::: -### Membuat keychain dan mendapatkan token testnet +### Generate a Keychain and Get Some Tokens Membuat keychain: ```bash -docker run -i node:14-alpine npx @stacks/cli make_keychain -t 2>/dev/null +docker run -i node:14-alpine npx @stacks/cli make_keychain 2>/dev/null | jq -r ``` -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 +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. -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). +### Update Stacks Blockchain Docker Configuration File -Perbarui properti berikut: +Use the steps oulined above to create the [configuration file](miner-testnet#update-the-stacks-blockchain-configuration-file) -```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 +### 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 ::: @@ -281,7 +226,8 @@ docker run -d \ --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" \ + -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 \ @@ -294,11 +240,13 @@ Anda dapat meninjau log noda dengan perintah ini: 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). +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). -Pastikan Anda telah menginstal prasyarat berikut di mesin Anda: +Ensure you have the following prerequisites installed: - [Docker](https://docs.docker.com/get-docker/) - [minikube](https://minikube.sigs.k8s.io/docs/start/) (Hanya diperlukan jika membuat klaster Kubernetes lokal) @@ -307,24 +255,18 @@ Pastikan Anda telah menginstal prasyarat berikut di mesin Anda: ### 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. +Use the steps [outlined above](miner-testnet#generate-a-keychain-and-get-some-tokens) ### 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 +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.node.seed="replace-with-your-privateKey-from-generate-keychain-step" \ ``` Anda dapat meninjau log noda dengan perintah ini: From d744efd1a9e305de9c565a80ce9bb9f68cf95d67 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:47:42 +0100 Subject: [PATCH 0673/1444] New translations stacks-node-configuration.md (Indonesian) --- .../stacks-node-configuration.md | 336 ++++++++++-------- 1 file changed, 190 insertions(+), 146 deletions(-) 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 index 9da4700db8..d90e4377a0 100644 --- 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 @@ -1,7 +1,7 @@ --- title: Konfigurasi Noda Stacks description: Parameter konfigurasi dan opsi untuk biner noda-stacks -sidebar_position: 6 +sidebar_position: 4 --- ## Pemakaian @@ -10,97 +10,141 @@ sidebar_position: 6 stacks-node sub-command [--subcommand-option ] ``` -## Subperintah +### Subcommands -:::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`: 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 -### mocknet +## Opsi File Konfigurasi -Memulai noda berdasarkan penyiapan lokal cepat yang meniru burnchain. Ideal untuk pengembangan kontrak pintar. +The Stacks Blockchain configuration file has multiple sections under which an option may be placed. -Contoh: +- [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) -```bash -stacks-node mocknet -``` +For reference, several configuration file examples are [available here](https://github.com/stacks-network/stacks-blockchain/tree/master/testnet/stacks-node/conf) -### krypton +- [Example mainnet follower configuration](./stacks-node-configuration#example-mainnet-follower-configuration) -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). +### node -Contoh: +Contains various configuration options for the stacks-node binary. -```bash -stacks-node krypton -``` +| Name | Required | Deskripsi | +| --------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------- | +| 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. | -### testnet +### events_observer -Start a node that will join and stream blocks from the public testnet. - -Contoh: - -```bash -stacks-node testnet -``` +:::info This section is _optional_ and not required -### mainnet +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. -Memulai noda yang bergabung dan mengalirkan blok dari mainnet publik. +| Name | Required | Deskripsi | +| ----------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| 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 | ✓ | 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: +### connection_options -```bash -stacks-node mainnet -``` +:::info This section is _optional_ and not required. -### mulai +However, if this section is added, **all** fields are required ::: -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. +Menentukan opsi konfigurasi untuk orang lain yang terhubung ke noda stacks. -#### Argumen +| Name | Required | Deskripsi | +| ------------------------------------ | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | +| 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 | -**--config**: jalur relatif atau absolut ke file konfigurasi TOML. Diperlukan. +### burnchain -Contoh: +Bagian ini berisi opsi konfigurasi yang berkaitan dengan blockchain yang diikat oleh noda-stacks di backend untuk proof-of-transfer (BTC). -```bash -stacks-node start --config=/path/to/config.toml -``` +| Name | Required | Deskripsi | +| --------- | -------- | ----------------------------------------------------------------------------------------------------------------------- | +| chain | ✓ | Noda-stacks blockchain mengikat pada backend untuk proof-of-transfer. Only value supported: `bitcoin` | +| mode | ✓ | Profil atau fase pengujian untuk menjalankan noda-stacks. 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` | -Lihat [Opsi File Konfigurasi](#configuration-file-options) untuk informasi lebih lanjut. +#### Penambangan -#### versi +| Name | Required | Deskripsi | +| ---------------------------- | -------- | ----------------------------------------------------------------------------------------------------- | +| 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 | | Menetapkan periode waktu (dalam milidetik) untuk komitmen. Only used when `mode` is set to `mocknet`. | -Menampilkan informasi tentang versi saat ini dan siklus rilis. +### ustx_balance -Contoh: +- `mocknet`/`testnet` only -```bash -stacks-node version -``` +This section contains configuration options allocating microSTX per address in the genesis block -#### bantuan +This section can repeat multiple times, but each section can only define a single address. -Menampilkan pesan bantuan. +:::info This section is only required for the `testnet` and `mocknet` networks. -Contoh: +However, if this section is added, **all** fields are required ::: -```bash -stacks-node help -``` +| Name | Required | Deskripsi | +| ------- | -------- | --------------------------------------------------------------------- | +| address | ✓ | Address which maintains a microSTX balance | +| amount | ✓ | The balance of microSTX given to the address at the start of the node | -## Opsi File Konfigurasi +## Example Mainnet Follower Configuration -File konfigurasi TOML memiliki beberapa bagian di mana opsi dapat ditempatkan. +```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" -Untuk melihat daftar contoh konfigurasi, [lihat halaman ini](https://github.com/stacks-network/stacks-blockchain/tree/master/testnet/stacks-node/conf) . +[burnchain] +chain = "bitcoin" +mode = "mainnet" +peer_host = "localhost" +username = "user" +password = "pass" +rpc_port = 8332 +peer_port = 8333 -### Bagian: noda +[[events_observer]] +endpoint = "localhost:3700" +retry_count = 255 +events_keys = ["*"] +``` -Berisi berbagai opsi konfigurasi yang berkaitan dengan noda-stacks. -Contoh: + From 3dc7e922cce4567a46db6d6df56b7e8cdb5c8cf0 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:47:43 +0100 Subject: [PATCH 0674/1444] New translations accounts.md (Indonesian) --- .../current/stacks-academy/accounts.md | 215 ++++++++++++++++++ 1 file changed, 215 insertions(+) create mode 100644 i18n/id/docusaurus-plugin-content-docs/current/stacks-academy/accounts.md diff --git a/i18n/id/docusaurus-plugin-content-docs/current/stacks-academy/accounts.md b/i18n/id/docusaurus-plugin-content-docs/current/stacks-academy/accounts.md new file mode 100644 index 0000000000..2261254023 --- /dev/null +++ b/i18n/id/docusaurus-plugin-content-docs/current/stacks-academy/accounts.md @@ -0,0 +1,215 @@ +--- +title: Akun +description: Panduan untuk akun Stacks 2.0 +sidebar_position: 7 +--- + +## 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. No person or organization can recover a lost seed phrase. +::: + +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, + 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 +); +``` + +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" + } + } + ] +} +``` From 16f5c7503d31cfa0cfa49efcedfcd28c1b4d92b1 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:47:44 +0100 Subject: [PATCH 0675/1444] New translations microblocks.md (Indonesian) --- .../current/stacks-academy/microblocks.md | 106 ++++++++++++++++++ 1 file changed, 106 insertions(+) create mode 100644 i18n/id/docusaurus-plugin-content-docs/current/stacks-academy/microblocks.md diff --git a/i18n/id/docusaurus-plugin-content-docs/current/stacks-academy/microblocks.md b/i18n/id/docusaurus-plugin-content-docs/current/stacks-academy/microblocks.md new file mode 100644 index 0000000000..3bd426a733 --- /dev/null +++ b/i18n/id/docusaurus-plugin-content-docs/current/stacks-academy/microblocks.md @@ -0,0 +1,106 @@ +--- +title: Mikroblok +description: Panduan untuk Mikroblok Stacks +sidebar_position: 5 +--- + +## Pengantar + +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. + +## 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. 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: + +``` +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. +... +``` + +Consider a similar transaction that is not included in a microblock: + +``` +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. +``` + +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. +::: + +## Mengaktifkan mikroblok + +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. + +### Transaksi + +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. + +### Penambangan + +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). + +## Mengembangkan dengan mikroblok + +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. + +## Praktik Terbaik + +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. + +### Menangani 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. + +### Desain Aplikasi + +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. + +#### Penjelajah + +Display pending state, but warn that a transaction is still pending. Indicate visually that displayed balances depend on pending state. + +#### Wallet + +Display pending state, but warn that a transaction is still pending. Indicate visually that displayed balances depend on pending state. + +#### Bursa + +Continue to count confirmations, microblocks should be considered pending. + +#### Aplikasi + +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. + +[provides an endpoint]: https://docs.hiro.so/get-started/stacks-blockchain-api#nonce-handling +[microblocks_api]: https://docs.hiro.so/api#tag/Microblocks From 8dcfe15c111276b7582fef87ef18bf50a2ea816f Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:47:45 +0100 Subject: [PATCH 0676/1444] New translations mining.md (Indonesian) --- .../current/stacks-academy/mining.md | 84 +++++++++++++++++++ 1 file changed, 84 insertions(+) create mode 100644 i18n/id/docusaurus-plugin-content-docs/current/stacks-academy/mining.md diff --git a/i18n/id/docusaurus-plugin-content-docs/current/stacks-academy/mining.md b/i18n/id/docusaurus-plugin-content-docs/current/stacks-academy/mining.md new file mode 100644 index 0000000000..10c4409671 --- /dev/null +++ b/i18n/id/docusaurus-plugin-content-docs/current/stacks-academy/mining.md @@ -0,0 +1,84 @@ +--- +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 testnet](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) + +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 + +## 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 From 9548b31902a97f9a16c29dc2d905c184c3a6db24 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:47:46 +0100 Subject: [PATCH 0677/1444] New translations network.md (Indonesian) --- .../current/stacks-academy/network.md | 148 ++++++++++++++++++ 1 file changed, 148 insertions(+) create mode 100644 i18n/id/docusaurus-plugin-content-docs/current/stacks-academy/network.md diff --git a/i18n/id/docusaurus-plugin-content-docs/current/stacks-academy/network.md b/i18n/id/docusaurus-plugin-content-docs/current/stacks-academy/network.md new file mode 100644 index 0000000000..11ab21b3f7 --- /dev/null +++ b/i18n/id/docusaurus-plugin-content-docs/current/stacks-academy/network.md @@ -0,0 +1,148 @@ +--- +title: Jaringan +description: Panduan jaringan Stacks 2.0 +sidebar_position: 5 +--- + +## 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 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 +} +``` From 577d4db36103012038d0f6b3f52d96b5557bde4f Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:47:47 +0100 Subject: [PATCH 0678/1444] New translations stacking.md (Indonesian) --- .../current/stacks-academy/stacking.md | 151 ++++++++++++++++++ 1 file changed, 151 insertions(+) create mode 100644 i18n/id/docusaurus-plugin-content-docs/current/stacks-academy/stacking.md diff --git a/i18n/id/docusaurus-plugin-content-docs/current/stacks-academy/stacking.md b/i18n/id/docusaurus-plugin-content-docs/current/stacks-academy/stacking.md new file mode 100644 index 0000000000..fb761601c0 --- /dev/null +++ b/i18n/id/docusaurus-plugin-content-docs/current/stacks-academy/stacking.md @@ -0,0 +1,151 @@ +--- +title: Stacking +description: Pengantar mekanisme hadiah Proof-of-Transfer +sidebar_position: 11 +--- + +## Pengantar + +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. 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. + +![](/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 Stacking functionality is implemented as a smart contract, using [Clarity](../clarity/). [Read more about the contract](../clarity/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 + +## 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 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 | 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) From bb2c8cfcb40eecad9b53c30ea8c5f12c109f9ea9 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:47:48 +0100 Subject: [PATCH 0679/1444] New translations technical-specs.md (Indonesian) --- .../current/stacks-academy/technical-specs.md | 79 +++++++++++++++++++ 1 file changed, 79 insertions(+) create mode 100644 i18n/id/docusaurus-plugin-content-docs/current/stacks-academy/technical-specs.md diff --git a/i18n/id/docusaurus-plugin-content-docs/current/stacks-academy/technical-specs.md b/i18n/id/docusaurus-plugin-content-docs/current/stacks-academy/technical-specs.md new file mode 100644 index 0000000000..c86954a037 --- /dev/null +++ b/i18n/id/docusaurus-plugin-content-docs/current/stacks-academy/technical-specs.md @@ -0,0 +1,79 @@ +--- +title: Spesifikasi Teknis +description: Ringkasan spesifikasi teknis Stacks 2.0 +sidebar_position: 13 +--- + +## 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). + +- [Watch Aaron Blankstein video on Stacks whitepaper v2](https://www.youtube.com/watch?v=Wd-Bfe8Sn-Y). From 2ecc34a3002a912a4d7fe4df4d6a43f4b3f18294 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:47:48 +0100 Subject: [PATCH 0680/1444] New translations testnet.md (Indonesian) --- .../current/stacks-academy/testnet.md | 35 +++++++++++++++++++ 1 file changed, 35 insertions(+) create mode 100644 i18n/id/docusaurus-plugin-content-docs/current/stacks-academy/testnet.md diff --git a/i18n/id/docusaurus-plugin-content-docs/current/stacks-academy/testnet.md b/i18n/id/docusaurus-plugin-content-docs/current/stacks-academy/testnet.md new file mode 100644 index 0000000000..9714abd1bf --- /dev/null +++ b/i18n/id/docusaurus-plugin-content-docs/current/stacks-academy/testnet.md @@ -0,0 +1,35 @@ +--- +title: Testnet +description: Uji kontrak dan aplikasi pintar Anda +sidebar_position: 12 +--- + +## Tentang testnet + +The testnet is a separate blockchain from the Stacks mainnet analogous to a staging environnement. Testnet adalah jaringan yang digunakan oleh pengembang untuk menguji aplikasi, kontrak pintar, atau perubahan protokol mereka dalam lingkungan seperti produksi. + +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 +::: + +### 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) From b337d457695dc345f911fad8df8e56c983219a17 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:47:49 +0100 Subject: [PATCH 0681/1444] New translations transactions.md (Indonesian) --- .../current/stacks-academy/transactions.md | 40 +++++++++++++++++++ 1 file changed, 40 insertions(+) create mode 100644 i18n/id/docusaurus-plugin-content-docs/current/stacks-academy/transactions.md diff --git a/i18n/id/docusaurus-plugin-content-docs/current/stacks-academy/transactions.md b/i18n/id/docusaurus-plugin-content-docs/current/stacks-academy/transactions.md new file mode 100644 index 0000000000..2c897fd76f --- /dev/null +++ b/i18n/id/docusaurus-plugin-content-docs/current/stacks-academy/transactions.md @@ -0,0 +1,40 @@ +--- +title: Transaksi +description: Panduan untuk transaksi Stacks 2.0 +sidebar_position: 9 +--- + +## 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). ::: From 20010e2b8475f123e5fba824a0b9b9120031ad64 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:47:51 +0100 Subject: [PATCH 0682/1444] New translations language-functions.md (Indonesian) --- .../current/clarity/language-functions.md | 2028 +++++++++++++++++ 1 file changed, 2028 insertions(+) create mode 100644 i18n/id/docusaurus-plugin-content-docs/current/clarity/language-functions.md diff --git a/i18n/id/docusaurus-plugin-content-docs/current/clarity/language-functions.md b/i18n/id/docusaurus-plugin-content-docs/current/clarity/language-functions.md new file mode 100644 index 0000000000..318545408c --- /dev/null +++ b/i18n/id/docusaurus-plugin-content-docs/current/clarity/language-functions.md @@ -0,0 +1,2028 @@ +--- +title: Fungsi +description: Lihat daftar rinci semua fungsi untuk bahasa Clarity. +sidebar_position: 3 +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: + +#### 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-existent\"))))) ;; 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-existent\") ;; 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-existent\" })) ;; 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-existent\" }))) ;; 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-existent\" }))) ;; 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 \"Stacks\" '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 successfully 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_ transferred from another principal, but rather minted. + +If a non-positive amount is provided to mint, this function returns `(err 1)`. Otherwise, on successfully 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_ transferred 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 successfully 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 successfully 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)) +``` From 40f964be5d2628763886c4e8ce5267c1fd295e29 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:47:52 +0100 Subject: [PATCH 0683/1444] New translations language-keywords.md (Indonesian) --- .../current/clarity/language-keywords.md | 147 ++++++++++++++++++ 1 file changed, 147 insertions(+) create mode 100644 i18n/id/docusaurus-plugin-content-docs/current/clarity/language-keywords.md diff --git a/i18n/id/docusaurus-plugin-content-docs/current/clarity/language-keywords.md b/i18n/id/docusaurus-plugin-content-docs/current/clarity/language-keywords.md new file mode 100644 index 0000000000..ca3a42eb57 --- /dev/null +++ b/i18n/id/docusaurus-plugin-content-docs/current/clarity/language-keywords.md @@ -0,0 +1,147 @@ +--- +title: Kata kunci +description: Lihat daftar rinci semua kata kunci untuk bahasa Clarity. +sidebar_position: 4 +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 + +``` From 62dcab9ee5c2b4185b968f680ff8134d4fb322ac Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:47:53 +0100 Subject: [PATCH 0684/1444] New translations language-types.md (Indonesian) --- .../current/clarity/language-types.md | 25 +++++++++++++++++++ 1 file changed, 25 insertions(+) create mode 100644 i18n/id/docusaurus-plugin-content-docs/current/clarity/language-types.md diff --git a/i18n/id/docusaurus-plugin-content-docs/current/clarity/language-types.md b/i18n/id/docusaurus-plugin-content-docs/current/clarity/language-types.md new file mode 100644 index 0000000000..b05ee33558 --- /dev/null +++ b/i18n/id/docusaurus-plugin-content-docs/current/clarity/language-types.md @@ -0,0 +1,25 @@ +--- +title: Tipe +description: Lihat daftar rinci semua tipe untuk bahasa Clarity. +sidebar_position: 2 +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. | From c4106135cbe2bb50a62869bb507bb5fd718e7675 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:47:56 +0100 Subject: [PATCH 0685/1444] New translations miner-costs-and-fees.md (Indonesian) --- .../current/nodes-and-miners/miner-costs-and-fees.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) 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 index 40397a51e0..dd8ee721cc 100644 --- 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 @@ -8,7 +8,7 @@ sidebar_position: 8 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 @@ -22,3 +22,5 @@ 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). From 199de18e67088952342c43bd2103773db3ebcc39 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:47:57 +0100 Subject: [PATCH 0686/1444] New translations verify-miner.md (Indonesian) --- .../current/nodes-and-miners/verify-miner.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) 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 index 094e3f03a1..18e8dd3a48 100644 --- 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 @@ -7,7 +7,7 @@ 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 +$ 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 -``` \ No newline at end of file +``` From 4135dc2c13a78b3b03ecbb8df1251b031e93c564 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:47:57 +0100 Subject: [PATCH 0687/1444] New translations stacks-blockchain-api.md (Indonesian) --- .../stacks-academy/stacks-blockchain-api.md | 41 +++++++++++++++++++ 1 file changed, 41 insertions(+) create mode 100644 i18n/id/docusaurus-plugin-content-docs/current/stacks-academy/stacks-blockchain-api.md diff --git a/i18n/id/docusaurus-plugin-content-docs/current/stacks-academy/stacks-blockchain-api.md b/i18n/id/docusaurus-plugin-content-docs/current/stacks-academy/stacks-blockchain-api.md new file mode 100644 index 0000000000..78b43dfe92 --- /dev/null +++ b/i18n/id/docusaurus-plugin-content-docs/current/stacks-academy/stacks-blockchain-api.md @@ -0,0 +1,41 @@ +--- +title: API Blockchain Stacks +description: Berinteraksi dengan Blockchain Stacks 2.0 melalui API +sidebar_position: 6 +--- + +## Pengantar +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. + +:::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. Untuk dokumentasi lengkap tentang API RESTful, lihat [referensi API Hiro](https://docs.hiro.so/api). ::: + +The RPC API can be used without any authorization. Jalur dasar untuk API adalah: + +```bash +# for mainnet, replace `testnet` with `mainnet` +https://stacks-node-api.testnet.stacks.co/ +``` + +## Endpoint API RPC Noda Stacks yang diproxy +The Stacks 2.0 Blockchain API (Hiro's API) is centrally hosted. 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. + +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`. ::: From 0f32d3a8a12f8fbde5a13ef33fb1def517ea1183 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:47:58 +0100 Subject: [PATCH 0688/1444] New translations run-a-node.md (Indonesian) --- .../current/nodes-and-miners/run-a-node.md | 329 +++--------------- 1 file changed, 42 insertions(+), 287 deletions(-) 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 index 94d938c5ca..2993568ce4 100644 --- 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 @@ -1,5 +1,5 @@ --- -title: Run a node +title: Run a Node with Docker description: Set up and run a Stacks node sidebar_position: 1 tags: @@ -8,344 +8,99 @@ tags: ## Stacks Blockchain with Docker -Run your own Stacks Blockchain node easily with just few commands. +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) -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](./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) -## **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 -``` +## **Requirements:** -- With optional proxy: +The **minimum viable requirements** are listed below. -```bash -./manage.sh -n -a start -f proxy -``` +While you _can_ run a node using these specs, it's _recommended_ to assign more than the minimum for better performance. -- With optional bitcoin node: +- ⚠️ [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_ ) -```bash -./manage.sh -n -a start -f bitcoin -``` +:::caution MacOS with an ARM processor is NOT recommended -5. **Stop the Services** +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. ::: -```bash -./manage.sh -n -a stop -``` - -6. **Retrieve Service Logs** - -```bash -./manage.sh -n -a logs -``` - -- Export docker log files to `./exported-logs`: +## **Quickstart** -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. +The `` placeholder used below can be replaced with one of: -```bash -./manage.sh -n -a logs export -``` +- mainnet +- testnet +- mocknet -7. **Restart all services** +1. **Clone the stacks-blockchain-docker repository locally** ```bash -./manage.sh -n -a restart +git clone https://github.com/stacks-network/stacks-blockchain-docker && cd stacks-blockchain-docker ``` -- With optional proxy: +2. **Start the Services** ```bash -./manage.sh -n -a restart -f proxy +./manage.sh -n -a start ``` -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. +:::note With an optional HTTP proxy on port 80: ```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. - +./manage.sh -n -a start -f proxy ``` -9. **Download BNS data to** `./persistent-data/bns-data` - -```bash -./manage.sh bns -``` +::: -10. **Export stacks-blockchain-api events** (_Not applicable for mocknet_) +## **Accessing the services** -```bash -./manage.sh -n -a export -# check logs for completion -./manage.sh -n -a restart -``` +:::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. -11. **Replay stacks-blockchain-api events** (_Not applicable for mocknet_) +Follow the logs to track the sync progress: ```bash -./manage.sh -n -a import -# check logs for completion -./manage.sh -n -a restart +./manage.sh -n -a logs ``` -## **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` +- Ports `20443-20444` are exposed on `localhost` ```bash -curl -sL localhost:20443/v2/info | jq +curl -sL localhost:20443/v2/info | jq -r ``` **stacks-blockchain-api**: -- Port `3999` are exposed to `localhost` +- Port `3999` is exposed on `localhost` ```bash -curl -sL localhost:3999/v2/info | jq +curl -sL localhost:3999 | jq -r ``` **proxy**: -- Port `80` is exposed to `localhost` +- Port `80` is exposed on `localhost` ```bash -curl -sL localhost/v2/info | jq -curl -sL localhost/ | jq +curl -sL localhost/v2/info | jq -r +curl -sL localhost | jq -r ``` --- ## 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 -``` +:::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): ::: --- - -## **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 From f8ba464a351880d6f7a5164a8ad724f2e011d5d8 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:47:59 +0100 Subject: [PATCH 0689/1444] New translations index.md (Indonesian) --- .../current/clarity/index.md | 58 +++++++++++++++++++ 1 file changed, 58 insertions(+) create mode 100644 i18n/id/docusaurus-plugin-content-docs/current/clarity/index.md diff --git a/i18n/id/docusaurus-plugin-content-docs/current/clarity/index.md b/i18n/id/docusaurus-plugin-content-docs/current/clarity/index.md new file mode 100644 index 0000000000..b51e6f9d8e --- /dev/null +++ b/i18n/id/docusaurus-plugin-content-docs/current/clarity/index.md @@ -0,0 +1,58 @@ +--- +title: Clarity Overview +description: Ringkasan dan panduan untuk memulai Clarity +sidebar_label: Clarity +sidebar_position: 5 +--- + +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. + +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?2 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. If you are unsure what this means, let it not worry you for now. The serious advantage of decidability will become more apparent over time. + +### 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. From ab04112c80373af6b02e8de70f9222606795c0b3 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:48:00 +0100 Subject: [PATCH 0690/1444] New translations index.md (Indonesian) --- .../current/stacks-academy/index.md | 11 +++++++++++ 1 file changed, 11 insertions(+) create mode 100644 i18n/id/docusaurus-plugin-content-docs/current/stacks-academy/index.md diff --git a/i18n/id/docusaurus-plugin-content-docs/current/stacks-academy/index.md b/i18n/id/docusaurus-plugin-content-docs/current/stacks-academy/index.md new file mode 100644 index 0000000000..a5bdb3c790 --- /dev/null +++ b/i18n/id/docusaurus-plugin-content-docs/current/stacks-academy/index.md @@ -0,0 +1,11 @@ +--- +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. From 0b35e56523b30b37075ba87a5c200b464bfecb5a Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:48:01 +0100 Subject: [PATCH 0691/1444] New translations proof-of-transfer.md (Indonesian) --- .../stacks-academy/proof-of-transfer.md | 83 +++++++++++++++++++ 1 file changed, 83 insertions(+) create mode 100644 i18n/id/docusaurus-plugin-content-docs/current/stacks-academy/proof-of-transfer.md diff --git a/i18n/id/docusaurus-plugin-content-docs/current/stacks-academy/proof-of-transfer.md b/i18n/id/docusaurus-plugin-content-docs/current/stacks-academy/proof-of-transfer.md new file mode 100644 index 0000000000..073bd8ce41 --- /dev/null +++ b/i18n/id/docusaurus-plugin-content-docs/current/stacks-academy/proof-of-transfer.md @@ -0,0 +1,83 @@ +--- +title: Proof of Transfer +description: Memahami mekanisme konsensus proof-of-transfer +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. + +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. + +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. + +![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. Thus, PoX blockchains are anchored on their chosen PoW chain. 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. Lastly, Bitcoin is largely considered a reliable store of value, and provides extensive infrastructure to support the PoX consensus mechanism. + +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). + +:::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. +::: + +## 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 + +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. + +![Membuka kunci 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. From 0cde5a1aa945fe069ee6fe4b0b6b239fdb54a78d Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:48:02 +0100 Subject: [PATCH 0692/1444] New translations what-is-stacks.md (Indonesian) --- .../current/stacks-academy/what-is-stacks.md | 102 ++++++++++++++++++ 1 file changed, 102 insertions(+) create mode 100644 i18n/id/docusaurus-plugin-content-docs/current/stacks-academy/what-is-stacks.md diff --git a/i18n/id/docusaurus-plugin-content-docs/current/stacks-academy/what-is-stacks.md b/i18n/id/docusaurus-plugin-content-docs/current/stacks-academy/what-is-stacks.md new file mode 100644 index 0000000000..94277da8a9 --- /dev/null +++ b/i18n/id/docusaurus-plugin-content-docs/current/stacks-academy/what-is-stacks.md @@ -0,0 +1,102 @@ +--- +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. + +There's a lot of jargon, possible assumptions, controversy, and cool technology wrapped up in those statements. So let's get started by getting a 30,000 foot view of what exactly Stacks is. + +## Stacks Explained in (Slightly Less Than) 10 Minutes + +
+ +
+ +## 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, Stacks takes a different approach. + +## 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). + +By taking this 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 with some unique properties, like having its own token, that allow it to maintain a historical ledger of all of its transactions and operate with its own security budget. + +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_. + +Nope. 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. From f252039849f960bf5e3bee9751a01d0154f6ffbd Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:48:03 +0100 Subject: [PATCH 0693/1444] New translations community-tutorials.md (Indonesian) --- .../current/tutorials/community-tutorials.md | 24 +++++++++++++++++++ 1 file changed, 24 insertions(+) create mode 100644 i18n/id/docusaurus-plugin-content-docs/current/tutorials/community-tutorials.md diff --git a/i18n/id/docusaurus-plugin-content-docs/current/tutorials/community-tutorials.md b/i18n/id/docusaurus-plugin-content-docs/current/tutorials/community-tutorials.md new file mode 100644 index 0000000000..a4f3d970ca --- /dev/null +++ b/i18n/id/docusaurus-plugin-content-docs/current/tutorials/community-tutorials.md @@ -0,0 +1,24 @@ +--- +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/) From b9ad10b7ce6ec00fce54eb2d828dabd54574a9ba Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:48:04 +0100 Subject: [PATCH 0694/1444] New translations hello-stacks.md (Indonesian) --- .../current/tutorials/hello-stacks.md | 759 ++++++++++++++++++ 1 file changed, 759 insertions(+) create mode 100644 i18n/id/docusaurus-plugin-content-docs/current/tutorials/hello-stacks.md diff --git a/i18n/id/docusaurus-plugin-content-docs/current/tutorials/hello-stacks.md b/i18n/id/docusaurus-plugin-content-docs/current/tutorials/hello-stacks.md new file mode 100644 index 0000000000..a0a442d135 --- /dev/null +++ b/i18n/id/docusaurus-plugin-content-docs/current/tutorials/hello-stacks.md @@ -0,0 +1,759 @@ +--- +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. From 7f89c6da2deee514ce35b6e1f3ccf12766a7b03d Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:48:04 +0100 Subject: [PATCH 0695/1444] New translations index.md (Indonesian) --- .../current/tutorials/index.md | 11 +++++++++++ 1 file changed, 11 insertions(+) create mode 100644 i18n/id/docusaurus-plugin-content-docs/current/tutorials/index.md diff --git a/i18n/id/docusaurus-plugin-content-docs/current/tutorials/index.md b/i18n/id/docusaurus-plugin-content-docs/current/tutorials/index.md new file mode 100644 index 0000000000..1d544c7bc1 --- /dev/null +++ b/i18n/id/docusaurus-plugin-content-docs/current/tutorials/index.md @@ -0,0 +1,11 @@ +--- +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. From e6f3a52ae0c60cda29671f72cead6d702e87d159 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:48:05 +0100 Subject: [PATCH 0696/1444] New translations satoshis-ridge.md (Indonesian) --- .../current/tutorials/satoshis-ridge.md | 75 +++++++++++++++++++ 1 file changed, 75 insertions(+) create mode 100644 i18n/id/docusaurus-plugin-content-docs/current/tutorials/satoshis-ridge.md diff --git a/i18n/id/docusaurus-plugin-content-docs/current/tutorials/satoshis-ridge.md b/i18n/id/docusaurus-plugin-content-docs/current/tutorials/satoshis-ridge.md new file mode 100644 index 0000000000..78b5079d15 --- /dev/null +++ b/i18n/id/docusaurus-plugin-content-docs/current/tutorials/satoshis-ridge.md @@ -0,0 +1,75 @@ +--- +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. + +## Prasyarat + +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 arguable one of its strengths. + +Instead, we need to create separate layers that add additional functionality without modify 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. From 4a867dd7d939f6f1492989f5370eb0e77e04b325 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:48:06 +0100 Subject: [PATCH 0697/1444] New translations crash-course.md (Indonesian) --- .../current/clarity/crash-course.md | 122 ++++++++++++++++++ 1 file changed, 122 insertions(+) create mode 100644 i18n/id/docusaurus-plugin-content-docs/current/clarity/crash-course.md diff --git a/i18n/id/docusaurus-plugin-content-docs/current/clarity/crash-course.md b/i18n/id/docusaurus-plugin-content-docs/current/clarity/crash-course.md new file mode 100644 index 0000000000..5b27a3c275 --- /dev/null +++ b/i18n/id/docusaurus-plugin-content-docs/current/clarity/crash-course.md @@ -0,0 +1,122 @@ +--- +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.md). + +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. + +```clojure +(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: + +```clojure +(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. From 58ab4660e19b690f7b5cf36580d485deda234119 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:48:07 +0100 Subject: [PATCH 0698/1444] New translations sample-contracts.md (Indonesian) --- .../current/clarity/sample-contracts.md | 14 ++++++++++++++ 1 file changed, 14 insertions(+) create mode 100644 i18n/id/docusaurus-plugin-content-docs/current/clarity/sample-contracts.md diff --git a/i18n/id/docusaurus-plugin-content-docs/current/clarity/sample-contracts.md b/i18n/id/docusaurus-plugin-content-docs/current/clarity/sample-contracts.md new file mode 100644 index 0000000000..adb12a58fd --- /dev/null +++ b/i18n/id/docusaurus-plugin-content-docs/current/clarity/sample-contracts.md @@ -0,0 +1,14 @@ +--- +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) From 04239d7737fff1aa73a587c5d1fa8216c266ce51 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:48:08 +0100 Subject: [PATCH 0699/1444] New translations index.md (Indonesian) --- .../current/cookbook/index.md | 64 +++++++++++++++++++ 1 file changed, 64 insertions(+) create mode 100644 i18n/id/docusaurus-plugin-content-docs/current/cookbook/index.md diff --git a/i18n/id/docusaurus-plugin-content-docs/current/cookbook/index.md b/i18n/id/docusaurus-plugin-content-docs/current/cookbook/index.md new file mode 100644 index 0000000000..d8948d8213 --- /dev/null +++ b/i18n/id/docusaurus-plugin-content-docs/current/cookbook/index.md @@ -0,0 +1,64 @@ +--- +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 + +Swapping between Bitcoin and Stacks addresses + +Swapping between xBTC and BTC + +Verifying a transaction on the BTC chain + +## DAOs + +Creating a simple DAO with ExecutorDAO + +Creating a BTC-backed DAO treasury + +## Token + +[Creating an NFT](./creating-an-nft) + +[Creating a Fungible Token](./creating-an-ft.md) + +Minting an NFT with Bitcoin + +Airdropping an NFT to a Bitcoin address + +## Stacking and Mining + +Simple stacking pool + +Continuous stacking + +Simple mining pool + +Proof of PoX payout + +## Oracles + +Creating a simple BTC price oracle + +## Frontend + +[Post conditions with Stacks.js](./post-conditions) + +[Authentication with Stacks.js](./stacks-js-auth) + +[Sending transactions with Stacks.js](./stacks-js-sending-transactions) + +## Complete Apps + +[Sup](https://github.com/kenrogers/sup) + +[Hello Stacks](https://github.com/kenrogers/hello-stacks) From 5f80f8a8af362c9fdcb2754d0d06c2ae87fd2116 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:48:09 +0100 Subject: [PATCH 0700/1444] New translations btc-connection.md (Indonesian) --- .../current/stacks-academy/btc-connection.md | 196 ++++++++++++++++++ 1 file changed, 196 insertions(+) create mode 100644 i18n/id/docusaurus-plugin-content-docs/current/stacks-academy/btc-connection.md diff --git a/i18n/id/docusaurus-plugin-content-docs/current/stacks-academy/btc-connection.md b/i18n/id/docusaurus-plugin-content-docs/current/stacks-academy/btc-connection.md new file mode 100644 index 0000000000..b4db915969 --- /dev/null +++ b/i18n/id/docusaurus-plugin-content-docs/current/stacks-academy/btc-connection.md @@ -0,0 +1,196 @@ +--- +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. + +## Stacks Among Other Bitcoin Layers + +In the [last section](./what-is-stacks.md) we covered what Stacks actually is and what problem it is solving, but this is not a new problem. The Bitcoin write problem has been a bit of a holy grail problem in the crypto world for a while now. + +Bitcoin is the OG cryptocurrency and has the largest market cap, but it also some of the least functionality, which means if we want to make it a productive asset and use it to build a decentralized economy, we need to take a layered approach and let Bitcoin do what it does best, while creating additional layers on top of it to add functionality. + +So how does Stacks compare to some of the other approaches to layering on top of Bitcoin? + +### 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. + +## 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. + +But because it has its own execution environment and smart contract state to maintain, it needs a token to incentivize maintenance of the network. + +But it goes further than that. It is possible to build a system like this without a token using something like merge-mining or a sidechain, but then we lose out on the additional benefit of having the chain state's safety underpinned by its entire token economy's value. + +In the case of Stacks, the safety and liveness of the chain are underpinned by this value, and the stacking mechanism incentivizes network members to increase this value. + +From Jude Nelson, Stacks core developer: + +"How hard is it to cause a safety failure (i.e. a double-spend via a reorg) on just the canonical Stacks chain fork? Anyone can become a miner by spending BTC, so without loss of generality, reverting the last block on the canonical chain is at least as hard in expectation as spending more BTC than the rest of the miners combined for that block. Because each Bitcoin block selects at most one Stacks block, the act of reorging the canonical Stacks chain back N blocks is the act of winning at least N + 1 blocks built off of a common ancestor that is N blocks deep. This is a lower bound on the number of Bitcoin blocks mined during which a reorg needs to take place — in practice, honest miners will keep working on the canonical chain, and will win some Stacks blocks of their own, which in turn increases the number of Stacks blocks the reorging miners must win. + +How costly is it to carry out a reorg of N blocks? It’s a function of how valuable STX is relative to BTC — the more valuable STX are, the more BTC honest miners are committing to mining (this has borne out in practice), and thus the more BTC a reorging miner must commit. Therefore, the cost of a reorg is a function of the value of STX. + +This is similar to the economic security of a PoW blockchain. Like in PoW, each fork of the Stacks chain has its own independent “security budget” — an attacker must out-spend the security budget to carry out a reorg, and the security budget is a function of the block rewards. In PoX, the only difference is that the miners spend another blockchain’s tokens (BTC in Stacks’ case) instead of energy. Therefore, Stacks can’t be a sidechain, a drivechain, or a merge-mined chain, because none of these other systems’ security budgets are a function of their tokens’ worth. Sidechains, drivechains, and merged-mined chains all rely on external miners for their safety, since their safety is guaranteed in part by external miners validating their blocks. The onus on these systems is to get external miners to care enough to do so, and in the case of sidechains, drivechains, and blind merged-mined chains, there is an additional onus to encourage their nodes to mine blocks at all (since there is no on-chain reward for them to earn by doing so). By contrast, disinterested Bitcoin miners neither assist nor prevent a reorg in PoX — they only record the history of all Stacks forks. + +PoX offers two additional, unique security properties on top of PoW. First, no matter how much BTC a reorging miner can commit, the act of executing a reorg is going to be time-consuming. Unless the attacker can attack the Bitcoin chain itself by quickly producing a better Bitcoin fork, a reorging miner must sustain the attack for at least N + 1 Bitcoin blocks. This gives honest miners and users ample time to notice and react to the reorg attempt. + +Second, the history of block production in all Stacks forks is embedded within Bitcoin. This allows the system to leverage Bitcoin’s security budget in order to ensure that all forks are public. This is because the act of producing a hidden Stacks fork, where the fork’s block hashes are not known to the honest miners, is the act of producing a hidden canonical Bitcoin fork. Therefore, the act of producing a hidden Stacks fork is at least as hard as reorging the Bitcoin chain. A PoX chain leverages this property not to prevent reorgs, but to make reorgs unprofitable. + +By anchoring blocks to an existing blockchain, a PoX chain forces reorgs to happen out in the open, thereby giving advance warning to all honest network participants when they happen. Honest miners, users, and exchanges will see the PoX transactions for reorg attempts on the existing blockchain, and adapt their behaviors accordingly: honest miners will increase their commitments, and users and exchanges will require more confirmations for transactions. This makes the act of carrying out a reorg while also making a profit much more challenging, since malicious reorgs — like selfish mining and double-spending — rely on secrecy to work effectively. Specific to Stacks, miners are additionally required to mine for a “warm-up” period of two blocks, during which they must spend BTC at their target commit levels but will not win any Stacks blocks. So, a high-budget reorg attempt will not only be costly, but will also alert the rest of the network before the damage is done." + +- [What Kind of Blockchain is Stacks?](https://stacks.org/stacks-blockchain) + +## 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) From 36fbbd3f318cbb81666244e33a870ee9cb0e59bb Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:48:10 +0100 Subject: [PATCH 0701/1444] New translations post-conditions.md (Indonesian) --- .../current/stacks-academy/post-conditions.md | 39 +++++++++++++++++++ 1 file changed, 39 insertions(+) create mode 100644 i18n/id/docusaurus-plugin-content-docs/current/stacks-academy/post-conditions.md diff --git a/i18n/id/docusaurus-plugin-content-docs/current/stacks-academy/post-conditions.md b/i18n/id/docusaurus-plugin-content-docs/current/stacks-academy/post-conditions.md new file mode 100644 index 0000000000..bb0727194f --- /dev/null +++ b/i18n/id/docusaurus-plugin-content-docs/current/stacks-academy/post-conditions.md @@ -0,0 +1,39 @@ +--- +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). From c027bf06731378881fc3a68ae7ea3a843922a5a2 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:48:10 +0100 Subject: [PATCH 0702/1444] New translations creating-an-ft.md (Indonesian) --- .../current/cookbook/creating-an-ft.md | 99 +++++++++++++++++++ 1 file changed, 99 insertions(+) create mode 100644 i18n/id/docusaurus-plugin-content-docs/current/cookbook/creating-an-ft.md diff --git a/i18n/id/docusaurus-plugin-content-docs/current/cookbook/creating-an-ft.md b/i18n/id/docusaurus-plugin-content-docs/current/cookbook/creating-an-ft.md new file mode 100644 index 0000000000..4e3bad99d2 --- /dev/null +++ b/i18n/id/docusaurus-plugin-content-docs/current/cookbook/creating-an-ft.md @@ -0,0 +1,99 @@ +--- +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) + ) +) +``` From 2e24fc320edd66962ef7bdff8ef22e0ef7074e8d Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:48:11 +0100 Subject: [PATCH 0703/1444] New translations creating-an-nft.md (Indonesian) --- .../current/cookbook/creating-an-nft.md | 87 +++++++++++++++++++ 1 file changed, 87 insertions(+) create mode 100644 i18n/id/docusaurus-plugin-content-docs/current/cookbook/creating-an-nft.md diff --git a/i18n/id/docusaurus-plugin-content-docs/current/cookbook/creating-an-nft.md b/i18n/id/docusaurus-plugin-content-docs/current/cookbook/creating-an-nft.md new file mode 100644 index 0000000000..08faf9393a --- /dev/null +++ b/i18n/id/docusaurus-plugin-content-docs/current/cookbook/creating-an-nft.md @@ -0,0 +1,87 @@ +--- +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 +Code for this recipe has been pulled from [this NFT tutorial](https://blog.developerdao.com/building-an-nft-with-stacks-and-clarity) from Developer DAO. +::: + +## 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) + ) +) +``` From a7a45b55f843902577ee3db3d4b47d6a61f3d269 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:48:12 +0100 Subject: [PATCH 0704/1444] New translations post-conditions.md (Indonesian) --- .../current/cookbook/post-conditions.md | 136 ++++++++++++++++++ 1 file changed, 136 insertions(+) create mode 100644 i18n/id/docusaurus-plugin-content-docs/current/cookbook/post-conditions.md diff --git a/i18n/id/docusaurus-plugin-content-docs/current/cookbook/post-conditions.md b/i18n/id/docusaurus-plugin-content-docs/current/cookbook/post-conditions.md new file mode 100644 index 0000000000..571fc20d48 --- /dev/null +++ b/i18n/id/docusaurus-plugin-content-docs/current/cookbook/post-conditions.md @@ -0,0 +1,136 @@ +--- +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. From 976b0bfc8e65abb5c2820da39acf696c821fbf9a Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:48:13 +0100 Subject: [PATCH 0705/1444] New translations stacks-js-auth.md (Indonesian) --- .../current/cookbook/stacks-js-auth.md | 98 +++++++++++++++++++ 1 file changed, 98 insertions(+) create mode 100644 i18n/id/docusaurus-plugin-content-docs/current/cookbook/stacks-js-auth.md diff --git a/i18n/id/docusaurus-plugin-content-docs/current/cookbook/stacks-js-auth.md b/i18n/id/docusaurus-plugin-content-docs/current/cookbook/stacks-js-auth.md new file mode 100644 index 0000000000..89d1f06e00 --- /dev/null +++ b/i18n/id/docusaurus-plugin-content-docs/current/cookbook/stacks-js-auth.md @@ -0,0 +1,98 @@ +--- +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 && ( + + ); +} +``` From 75055f788d0d886da17154fbf5e3347cb5191e8a Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:48:14 +0100 Subject: [PATCH 0706/1444] New translations stacks-js-sending-transactions.md (Indonesian) --- .../stacks-js-sending-transactions.md | 55 +++++++++++++++++++ 1 file changed, 55 insertions(+) create mode 100644 i18n/id/docusaurus-plugin-content-docs/current/cookbook/stacks-js-sending-transactions.md diff --git a/i18n/id/docusaurus-plugin-content-docs/current/cookbook/stacks-js-sending-transactions.md b/i18n/id/docusaurus-plugin-content-docs/current/cookbook/stacks-js-sending-transactions.md new file mode 100644 index 0000000000..849c7d1f42 --- /dev/null +++ b/i18n/id/docusaurus-plugin-content-docs/current/cookbook/stacks-js-sending-transactions.md @@ -0,0 +1,55 @@ +--- +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. From 39c235a19e3ace037d728c3ebad04578290add5b Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:48:14 +0100 Subject: [PATCH 0707/1444] New translations _category_.json (Indonesian) --- .../current/clarity/noteworthy-contracts/_category_.json | 8 ++++++++ 1 file changed, 8 insertions(+) create mode 100644 i18n/id/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/_category_.json diff --git a/i18n/id/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/_category_.json b/i18n/id/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/_category_.json new file mode 100644 index 0000000000..f5de305558 --- /dev/null +++ b/i18n/id/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/_category_.json @@ -0,0 +1,8 @@ +{ + "label": "Noteworthy Contracts", + "position": 4, + "link": { + "type": "generated-index", + "description": "Specific deployed Clarity Contracts worth mentioning." + } +} \ No newline at end of file From 426ac304f41e67dc032c6ae3685bf65fcd623198 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:48:15 +0100 Subject: [PATCH 0708/1444] New translations bns-contract.md (Indonesian) --- .../noteworthy-contracts/bns-contract.md | 519 ++++++++++++++++++ 1 file changed, 519 insertions(+) create mode 100644 i18n/id/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/bns-contract.md diff --git a/i18n/id/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/bns-contract.md b/i18n/id/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/bns-contract.md new file mode 100644 index 0000000000..a500af3f22 --- /dev/null +++ b/i18n/id/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/bns-contract.md @@ -0,0 +1,519 @@ +--- +title: BNS Contract +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: + +- [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` From 285862750b195e2a921d9798d03fbf2d015515a9 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:48:16 +0100 Subject: [PATCH 0709/1444] New translations xbtc.md (Indonesian) --- .../clarity/noteworthy-contracts/xbtc.md | 28 +++++++++++++++++++ 1 file changed, 28 insertions(+) create mode 100644 i18n/id/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/xbtc.md diff --git a/i18n/id/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/xbtc.md b/i18n/id/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/xbtc.md new file mode 100644 index 0000000000..8e6ced96fb --- /dev/null +++ b/i18n/id/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/xbtc.md @@ -0,0 +1,28 @@ +--- +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/) 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) From 0b54e5b773ed9195eac3cef7c9e5e65a71440f5f Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:48:17 +0100 Subject: [PATCH 0710/1444] New translations index.md (Indonesian) --- .../current/glossary/index.md | 284 ++++++++++++++++++ 1 file changed, 284 insertions(+) create mode 100644 i18n/id/docusaurus-plugin-content-docs/current/glossary/index.md diff --git a/i18n/id/docusaurus-plugin-content-docs/current/glossary/index.md b/i18n/id/docusaurus-plugin-content-docs/current/glossary/index.md new file mode 100644 index 0000000000..419c0e0d73 --- /dev/null +++ b/i18n/id/docusaurus-plugin-content-docs/current/glossary/index.md @@ -0,0 +1,284 @@ +--- +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. From 99ef2559426a1fb8f46db8bd1b3511acf647dd4b Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:48:18 +0100 Subject: [PATCH 0711/1444] New translations quicknode.md (Indonesian) --- .../current/nodes-and-miners/quicknode.md | 45 +++++++++++++++++++ 1 file changed, 45 insertions(+) create mode 100644 i18n/id/docusaurus-plugin-content-docs/current/nodes-and-miners/quicknode.md diff --git a/i18n/id/docusaurus-plugin-content-docs/current/nodes-and-miners/quicknode.md b/i18n/id/docusaurus-plugin-content-docs/current/nodes-and-miners/quicknode.md new file mode 100644 index 0000000000..1281964689 --- /dev/null +++ b/i18n/id/docusaurus-plugin-content-docs/current/nodes-and-miners/quicknode.md @@ -0,0 +1,45 @@ +--- +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. From 086c46c8fbdb99021785c5df8c7aa5ec7d959dbc Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:48:19 +0100 Subject: [PATCH 0712/1444] New translations defi.md (Indonesian) --- .../current/services-using-stacks/defi.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) 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 index 51defacba7..58717a3234 100644 --- 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 @@ -26,7 +26,7 @@ Please edit this page to add any relevant new site that we are missing. ## Lnswap -[LNSWAP](https://www.lnswap.org). Non custiodial crypto currency exchange +[LNSWAP](https://www.lnswap.org). Non-custodial crypto currency exchange ![](/img/sh_lnswap.png) @@ -41,4 +41,3 @@ Please edit this page to add any relevant new site that we are missing. [Stackswap](https://app.stackswap.org/v2) ![](/img/sh_stackswap.png) - From d9b80df117db04c0989345ad81736c9711956edf Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:48:20 +0100 Subject: [PATCH 0713/1444] New translations more.md (Indonesian) --- .../current/services-using-stacks/more.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) 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 index df0b3e2254..1e14b9a5a5 100644 --- 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 @@ -18,6 +18,6 @@ Please edit this page to add any relevant new site that we are missing. ## Sigle -[Sigle](https://www.sigle.io/) is a decentralised and open source web 3 writing platform. +[Sigle](https://www.sigle.io/) is a decentralized and open source web 3 writing platform. -![](/img/sh_sigle.png) \ No newline at end of file +![](/img/sh_sigle.png) From 41ec0b74a9898e40d768c501ce786df5ac6951b8 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:48:21 +0100 Subject: [PATCH 0714/1444] New translations nft.md (Indonesian) --- .../current/services-using-stacks/nft.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) 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 index abb770663c..d582604854 100644 --- 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 @@ -15,6 +15,7 @@ Please edit this page to add any relevant new site that we are missing. ![website-screenshot](/img/sh_nft_byzantion.png) ### [Gamma](https://gamma.io/) + ![website-screenshot](/img/sh_nft_gamma.png) ### [Megapont](https://www.megapont.com/) @@ -35,4 +36,4 @@ Please edit this page to add any relevant new site that we are missing. ### [Superfandom](https://superfandom.io/) -![website-screenshot](/img/sh_superfandom.png) \ No newline at end of file +![website-screenshot](/img/sh_superfandom.png) From c7687be73419a9bd33a98da35f5996392e112fae Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:48:21 +0100 Subject: [PATCH 0715/1444] New translations stacks-info-sites.md (Indonesian) --- .../current/services-using-stacks/stacks-info-sites.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) 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 index 5ad27b2901..54f6823e33 100644 --- 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 @@ -1,10 +1,10 @@ --- -title: Situs info Stacks +title: Stacks info sites description: Status and stats of the Stacks network. sidebar_position: 1 --- -Daftar situs berdasarkan abjad yang menampilkan status dan statistik jaringan Stacks. +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. @@ -30,7 +30,7 @@ Please edit this page to add any relevant new site that we are missing. ![website-screenshot](/img/sh_stxstats.png) -### [Novuminsights](https://stacks.novuminsights.com/health) +### [Novum Insights](https://stacks.novuminsights.com/health) ![website-screenshot](/img/sh_novuminsights.png) From f103254c823fb681cc2e7b721921d60c525561b6 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:48:22 +0100 Subject: [PATCH 0716/1444] New translations wallets.md (Indonesian) --- .../current/services-using-stacks/wallets.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) 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 index e33ca3010d..f942cd3b1f 100644 --- 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 @@ -15,6 +15,7 @@ Please edit this page to add any relevant new site that we are missing. [Blockchain.com](https://www.blockchain.com/wallet) ![](/img/sh_blockchain.png) + ## Boom [Boom](https://boom.money) @@ -26,6 +27,7 @@ Please edit this page to add any relevant new site that we are missing. [D'CENT](https://dcentwallet.com) ![](/img/sh_dcent.png) + ## Hiro Wallet [Hiro Wallet](https://www.hiro.so/wallet) @@ -48,4 +50,4 @@ Please edit this page to add any relevant new site that we are missing. [Wise](https://wiseapp.id) -![](/img/sh_wiseapp.png) \ No newline at end of file +![](/img/sh_wiseapp.png) From 5fb125ac038e7c92fca905c07c1620241ab9257c Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:48:23 +0100 Subject: [PATCH 0717/1444] New translations whitepapers.md (Indonesian) --- .../current/stacks-academy/whitepapers.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) create mode 100644 i18n/id/docusaurus-plugin-content-docs/current/stacks-academy/whitepapers.md diff --git a/i18n/id/docusaurus-plugin-content-docs/current/stacks-academy/whitepapers.md b/i18n/id/docusaurus-plugin-content-docs/current/stacks-academy/whitepapers.md new file mode 100644 index 0000000000..0e564fbf44 --- /dev/null +++ b/i18n/id/docusaurus-plugin-content-docs/current/stacks-academy/whitepapers.md @@ -0,0 +1,12 @@ +--- +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) From cdcefe93274f43c814687ae67fd9a7d512c67237 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:48:24 +0100 Subject: [PATCH 0718/1444] New translations stacking-contract.md (Indonesian) --- .../noteworthy-contracts/stacking-contract.md | 352 ++++++++++++++++++ 1 file changed, 352 insertions(+) create mode 100644 i18n/id/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/stacking-contract.md diff --git a/i18n/id/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/stacking-contract.md b/i18n/id/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/stacking-contract.md new file mode 100644 index 0000000000..749679a4fa --- /dev/null +++ b/i18n/id/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/stacking-contract.md @@ -0,0 +1,352 @@ +--- +title: Stacking Contract +description: See a detailed list of all functions and error codes of the Stacking contract. +sidebar_position: 6 +--- + +## Pengantar + +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` From 30ed6e09aa5a2042ab340c172011657f3236325f Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:48:25 +0100 Subject: [PATCH 0719/1444] New translations index.md (Indonesian) --- .../current/next-steps/index.md | 39 +++++++++++++++++++ 1 file changed, 39 insertions(+) create mode 100644 i18n/id/docusaurus-plugin-content-docs/current/next-steps/index.md diff --git a/i18n/id/docusaurus-plugin-content-docs/current/next-steps/index.md b/i18n/id/docusaurus-plugin-content-docs/current/next-steps/index.md new file mode 100644 index 0000000000..00ddec9178 --- /dev/null +++ b/i18n/id/docusaurus-plugin-content-docs/current/next-steps/index.md @@ -0,0 +1,39 @@ +--- +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) From 51424be8250bfb96b3adbc2ae93c1ab3e4852aaa Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:48:26 +0100 Subject: [PATCH 0720/1444] New translations sips.md (Indonesian) --- .../current/stacks-academy/sips.md | 52 +++++++++++++++++++ 1 file changed, 52 insertions(+) create mode 100644 i18n/id/docusaurus-plugin-content-docs/current/stacks-academy/sips.md diff --git a/i18n/id/docusaurus-plugin-content-docs/current/stacks-academy/sips.md b/i18n/id/docusaurus-plugin-content-docs/current/stacks-academy/sips.md new file mode 100644 index 0000000000..aa2db18e62 --- /dev/null +++ b/i18n/id/docusaurus-plugin-content-docs/current/stacks-academy/sips.md @@ -0,0 +1,52 @@ +--- +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/IJ15791776) 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-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. From c3b0252359f634685fc974e4e9db070c8f559d7b Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:48:27 +0100 Subject: [PATCH 0721/1444] New translations hosted-nodes.md (Indonesian) --- .../current/nodes-and-miners/hosted-nodes.md | 25 +++++++++++++++++++ 1 file changed, 25 insertions(+) create mode 100644 i18n/id/docusaurus-plugin-content-docs/current/nodes-and-miners/hosted-nodes.md diff --git a/i18n/id/docusaurus-plugin-content-docs/current/nodes-and-miners/hosted-nodes.md b/i18n/id/docusaurus-plugin-content-docs/current/nodes-and-miners/hosted-nodes.md new file mode 100644 index 0000000000..12d86c7ee2 --- /dev/null +++ b/i18n/id/docusaurus-plugin-content-docs/current/nodes-and-miners/hosted-nodes.md @@ -0,0 +1,25 @@ +--- +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. From cbfa4af03889851f29153c2b970edb6007161de9 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:48:27 +0100 Subject: [PATCH 0722/1444] New translations authentication.md (Hindi) --- .../current/stacks-academy/authentication.md | 63 +++++++++++++++++++ 1 file changed, 63 insertions(+) create mode 100644 i18n/hi/docusaurus-plugin-content-docs/current/stacks-academy/authentication.md diff --git a/i18n/hi/docusaurus-plugin-content-docs/current/stacks-academy/authentication.md b/i18n/hi/docusaurus-plugin-content-docs/current/stacks-academy/authentication.md new file mode 100644 index 0000000000..02296a19a3 --- /dev/null +++ b/i18n/hi/docusaurus-plugin-content-docs/current/stacks-academy/authentication.md @@ -0,0 +1,63 @@ +--- +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 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. From d738973454a1150598b966e5bd39276e4d2a5bbb Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:48:28 +0100 Subject: [PATCH 0723/1444] New translations bns.md (Hindi) --- .../current/stacks-academy/bns.md | 242 ++++++++++++++++++ 1 file changed, 242 insertions(+) create mode 100644 i18n/hi/docusaurus-plugin-content-docs/current/stacks-academy/bns.md diff --git a/i18n/hi/docusaurus-plugin-content-docs/current/stacks-academy/bns.md b/i18n/hi/docusaurus-plugin-content-docs/current/stacks-academy/bns.md new file mode 100644 index 0000000000..4c89d9e56c --- /dev/null +++ b/i18n/hi/docusaurus-plugin-content-docs/current/stacks-academy/bns.md @@ -0,0 +1,242 @@ +--- +title: Blockchain Naming System +description: Binds Stacks usernames to off-chain state +sidebar_position: 8 +--- + +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 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). From 1ff574ba17792d8f842a1bb039b723827a6935a7 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:48:29 +0100 Subject: [PATCH 0724/1444] New translations docs.md (Hindi) --- .../current/contribute/docs.md | 24 ++++++++++++------- 1 file changed, 15 insertions(+), 9 deletions(-) diff --git a/i18n/hi/docusaurus-plugin-content-docs/current/contribute/docs.md b/i18n/hi/docusaurus-plugin-content-docs/current/contribute/docs.md index 77705451b8..b2fef628f9 100644 --- a/i18n/hi/docusaurus-plugin-content-docs/current/contribute/docs.md +++ b/i18n/hi/docusaurus-plugin-content-docs/current/contribute/docs.md @@ -7,7 +7,7 @@ description: Learn how this site is built, and how you can contribute to it. 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). +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/). @@ -15,7 +15,7 @@ Don't want to learn it? No need to. Write [in plain text an issue on Github](htt :::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 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). @@ -24,28 +24,32 @@ To add new content, they are two different ways to do it, the [easy way](#easy-w [**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. +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 yourhanges in real time. + - `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. -## Aditional information +## 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 ``` @@ -54,8 +58,8 @@ Before running this command for the first time you will need to run `npm install 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 ``` @@ -91,7 +95,7 @@ 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. +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 @@ -124,6 +128,7 @@ And execute prettier with the following command: npx prettier --write mynewfiletocheck.md ``` --> + ### 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. @@ -138,6 +143,7 @@ To write a code block, you need to wrap your code in ` ```language `, and end yo (define-public (get-counter) (ok (var-get counter))) ``` + ### Admonitions You can use the following admonitions to highlight content. @@ -204,4 +210,4 @@ Some **content** with _markdown_ `syntax`. Some **content** with _markdown_ `syntax`. -::: \ No newline at end of file +::: From 654037d2d1ff541992f3d19283cae36001653303 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:48:31 +0100 Subject: [PATCH 0725/1444] New translations translations.md (Hindi) --- .../current/contribute/translations.md | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/i18n/hi/docusaurus-plugin-content-docs/current/contribute/translations.md b/i18n/hi/docusaurus-plugin-content-docs/current/contribute/translations.md index bd9a452333..fe8f8c6027 100644 --- a/i18n/hi/docusaurus-plugin-content-docs/current/contribute/translations.md +++ b/i18n/hi/docusaurus-plugin-content-docs/current/contribute/translations.md @@ -1,25 +1,24 @@ --- title: Contribute with translations -description: Want to help tranlating these docs to your local language? +description: Want to help translating 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. +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 Crodin intead. +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 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 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) From ec667562d0db64fb3887222719156e4b13e55930 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:48:33 +0100 Subject: [PATCH 0726/1444] New translations gaia-on-ec2.md (Hindi) --- .../current/gaia/gaia-on-ec2.md | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) 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 index 2067e7d57c..3f58ca5e68 100644 --- 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 @@ -26,9 +26,10 @@ Use a link in the table to launch the [CloudFormation](https://console.aws.amazo ### Step 2 - Setup stack using template -You need to configure the template with the appropiate values for your hub and domain it runs on. +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 ``` @@ -52,7 +53,7 @@ Specify the stack details and then click `Next`: ![Specify template](/img/cloudf | 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`. | +| 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 | @@ -93,7 +94,9 @@ ssh -i admin@ 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 +![](/img/cloudformation-gaia-template1-designer.png) From 30d071a5e4eeb1e90f6fb3e7ba54e1e5581c5be9 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:48:34 +0100 Subject: [PATCH 0727/1444] New translations gaia.md (Hindi) --- .../current/gaia/gaia.md | 12 +++++++++--- 1 file changed, 9 insertions(+), 3 deletions(-) diff --git a/i18n/hi/docusaurus-plugin-content-docs/current/gaia/gaia.md b/i18n/hi/docusaurus-plugin-content-docs/current/gaia/gaia.md index 1070857350..f86a0d61dc 100644 --- a/i18n/hi/docusaurus-plugin-content-docs/current/gaia/gaia.md +++ b/i18n/hi/docusaurus-plugin-content-docs/current/gaia/gaia.md @@ -1,14 +1,20 @@ --- title: Gaia description: Decentralized storage architecture for off-chain data -sidebar_position: 5 +sidebar_position: 6 tags: - gaia --- ## Introduction -Apps built with the Stacks blockchain store off-chain data using a storage system called Gaia. +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. @@ -38,7 +44,7 @@ The Stacks blockchain stores only identity data. Data created by the actions of 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) +![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. From 6ea98dd7c60d726dbd7b7d226016898e0a0dce15 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:48:35 +0100 Subject: [PATCH 0728/1444] New translations setup-linux.md (Hindi) --- .../current/gaia/setup-linux.md | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) 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 index db427f890a..2c0ca2b92e 100644 --- a/i18n/hi/docusaurus-plugin-content-docs/current/gaia/setup-linux.md +++ b/i18n/hi/docusaurus-plugin-content-docs/current/gaia/setup-linux.md @@ -1,6 +1,6 @@ --- 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. +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 @@ -19,8 +19,7 @@ This configuration will setup the following 4 docker containers: 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: +**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 @@ -48,8 +47,7 @@ chmod +x ${DESTINATION_DC}/docker-compose 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. +**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 From 81b007dc55608972556d81a2f1f097da44c74e69 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:48:36 +0100 Subject: [PATCH 0729/1444] New translations digitalocean.md (Hindi) --- .../current/nodes-and-miners/digitalocean.md | 41 +++++++++++-------- 1 file changed, 25 insertions(+), 16 deletions(-) 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 index dd7194f504..15df918d04 100644 --- 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 @@ -1,28 +1,30 @@ --- -title: Stacks on DigitalOcean +title: Run a Node with Digital Ocean description: A guide to setup Stacks on DigitalOcean -sidebar_position: 4 +sidebar_position: 2 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). +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`. +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 plan that meets the minimum requirements) and your prefered datacenter region. ![](/img/sh_digitalocean-choose-plan.png) +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 if your prefer. +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) @@ -46,41 +48,48 @@ Congratulations! You are now running the Stacks Blockchain. You can click on `Co ## 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). +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`. -Once the stacks blockchain starts to sync with peers, application ports will open and nginx port 80 will now start proxying requests. +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 v3.0.3 (master:cd0c8aef)", + "server_version": "stacks-blockchain-api v6.2.3 (master:77ab3ae2)", "status": "ready", "chain_tip": { - "block_height": 16220, - "block_hash": "0x3123fba9c0de6b569573494cf83c1d5d198a66bfd5f48ef97949b6bf11ba13be", - "index_block_hash": "0xeec960fbbd6186b4ccac85ce12adba72be497d881f81e077305c90955b51a6ae" + "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/README.md#quickstart). +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). -## API Creation +## 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 -curl -X POST -H 'Content-Type: application/json' \ +$ export TOKEN= +$ 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"}' \ + '{"name":"stacks-blockchain","region":"sfo2","size":"s-2vcpu-4gb","image":"stacksfoundation-stacksblockchain"}' \ "https://api.digitalocean.com/v2/droplets" ``` From 92cb92e2c9b10a0ccf0d6cd7963e6354e57b42a1 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:48:37 +0100 Subject: [PATCH 0730/1444] New translations index.md (Hindi) --- .../current/nodes-and-miners/index.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) 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 index b6cbb9754a..e5f4f2c250 100644 --- 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 @@ -1,11 +1,11 @@ --- title: Nodes and Miners description: Nodes and Miners -sidebar_position: 7 +sidebar_position: 5 --- -Here are all the steps to run nodes and miners, both on mainnet and testnet. +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. -## What's a Stacks node? +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. -## What's a Stacks miner? +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. From e077c6b976523ffdaa1f43927e2d951e8894ad9b Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:48:38 +0100 Subject: [PATCH 0731/1444] New translations miner-mainnet.md (Hindi) --- .../current/nodes-and-miners/miner-mainnet.md | 301 +++++++----------- 1 file changed, 110 insertions(+), 191 deletions(-) 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 index 468a01df66..5afd34c23f 100644 --- 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 @@ -1,166 +1,100 @@ --- title: Mine mainnet Stacks tokens -description: Set up and run a miner on the Stacks 2.0 mainnet -sidebar_position: 5 +description: Set up and run a miner on Stacks Mainnet +sidebar_position: 6 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. +For more on the technical details of mining, please review the [mining guide](../stacks-academy/mining) -If you're interested in mining on the testnet, you can find instructions on how to do that [here](miner-testnet): +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 want to learn more about the technical details of mining, please review the [mining guide](../understand-stacks/mining): +If you're interested in mining on the Stacks testnet, you can find instructions on how to do that [here](miner-testnet): -## Running bitcoind locally +## Running a Bitcoin Mainnet Full Node -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) +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. -First, download the bitcoind software for your platform from https://bitcoin.org/en/download. +- [Ensure your computer meets the minimum hardware requirements before continuing.](https://bitcoin.org/en/bitcoin-core/features/requirements#system-requirements) -Next, start bitcoind with the following configuration: +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): -```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 -``` +:::tip It is recommened to use a persistent location for the chainstate, in the steps below we're using `/bitcoin` ::: -Finally, start bitcoind as follows: +### Update the Bitcoin Configuration File -```bash -bitcoind -conf=path/to/bitcoin.conf -``` - -It may take a few days for the node to synchronize with the Bitcoin mainnet. +Next, update the bitcoin configuration: -## 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: +- **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 -[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 = "" -... +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 ``` -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. +### Start Bitcoin -To run your miner, run this in the command line: +Finally, start bitcoin as follows (adjust the `conf` path to where it was created in the previous step, i.e. `$HOME/bitcoin.conf`): ```bash -stacks-node start --config=./testnet/stacks-node/conf/mainnet-miner-conf.toml +bitcoind -conf=$HOME/bitcoin.conf ``` -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 -``` +:::note +It will take a few days for the node to synchronize with Bitcoin mainnet. +::: -The above code will compile an optimized binary. To use it, run: +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 -cd ../.. -./target/release/stacks-node start --config=./mainnet-miner-conf.toml +$ bitcoin-cli \ + -rpcconnect=localhost \ + -rpcport=8332 \ + -rpcuser=btcuser \ + -rpcpassword=btcpassword \ +getblockchaininfo | jq .blocks +773281 ``` -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 Stacks Blockchain miner -## Running a miner in Windows +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) -### Prerequisites +_There may be some extra requirements to building, [defined here](https://github.com/stacksfoundation/miner-docs/blob/main/prerequisites.md#install-required-packages)_ -Make sure are [running a node](run-a-node) and [running bitcoind locally](#running-bitcoind-locally) before starting this tutorial. +:::tip It is recommened to use a persistent location for the chainstate, in the steps below we're using `/stacks-blockchain` ::: -### Generate keychain and get mainnet tokens in Windows +### Generate a keychain -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 cryptocurrency 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: +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 -npm install --global @stacks/cli -stx make_keychain > cli_keychain.json -type cli_keychain.json +npx @stacks/cli make_keychain 2>/dev/null | jq -r ``` -After this runs, you'll probably see some installation logs, and at the end you should see some JSON that looks like this: +After this runs, you should see some JSON printed to the screen that looks like this: ```json { @@ -174,109 +108,99 @@ After this runs, you'll probably see some installation logs, and at the end you } ``` -:::tip Check out the [Stacks CLI reference](https://docs.hiro.so/references/stacks-cli) for more details ::: +:::warning **Do not lose this information** - we'll need to use the `privateKey` and `btcAddress` fields in later steps. ::: -The above BTC address will then need to be imported into the BTC network. +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=your-user -rpcpassword=your-password importaddress +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 configuration file + + +### Update the Stacks Blockchain 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). +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`. -Update the following properties: +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] -... -# Enter your private key here -seed = "replace-with-your-private-key" -local_peer_seed = "replace-with-your-private-key" -... +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] -... -# To mine on mainnet, you need to run bitcoind locally -# Details can be found in above section, 'Running bitcoind locally' +chain = "bitcoin" +mode = "mainnet" peer_host = "127.0.0.1" -username = "" -password = "" -... +username = "" +password = "" +rpc_port = 8332 +peer_port = 8333 +satoshis_per_byte = 100 +burn_fee_cap = 20000 ``` -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 +### Start the Stacks Blockchain -To start your miner, run this in the command line: +To run your miner, run this in the command line: ```bash -stacks-node start --config=testnet/stacks-node/conf/mainnet-miner-conf.toml +stacks-node start --config=$HOME/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 +### 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 -set RUST_BACKTRACE=full; -set STACKS_LOG_DEBUG=1; -stacks-node start --config=mainnet-miner-conf.toml +STACKS_LOG_DEBUG=1 stacks-node start --config=$HOME/mainnet-miner-conf.toml ``` -## Optional: Running with Docker +--- + +## Optional: Running a Stacks Blockchain miner with Docker -Alternatively, you can run the mainnet node with Docker. +Alternatively, you can run a Stacks mainnet miner with Docker. -:::caution Ensure you have [Docker](https://docs.docker.com/get-docker/) installed on your machine. ::: +:::caution Ensure you have [Docker](https://docs.docker.com/get-docker/) installed. ::: -### Generate keychain and get tokens +### 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 +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 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: +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). -```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 = "" -... -``` +### Update Stacks Blockchain Docker Configuration File -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. +Use the steps oulined above to create the [configuration file](miner-mainnet#update-the-stacks-blockchain-configuration-file) -### Start the miner +### 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 ::: @@ -287,7 +211,8 @@ docker run -d \ --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" \ + -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 \ @@ -302,9 +227,9 @@ 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). +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 on your machine: +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) @@ -313,13 +238,7 @@ Ensure you have the following prerequisites installed on your machine: ### 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). +Use the steps [outlined above](miner-mainnet#generate-a-keychain-and-get-some-tokens) ### Install the chart and run the miner From 00ea3046cf09d12fdf6bc2b22b109de564e6ecc6 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:48:39 +0100 Subject: [PATCH 0732/1444] New translations miner-testnet.md (Hindi) --- .../current/nodes-and-miners/miner-testnet.md | 318 +++++++----------- 1 file changed, 130 insertions(+), 188 deletions(-) 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 index b572df3ba2..c0a27e63d5 100644 --- 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 @@ -1,35 +1,52 @@ --- title: Mine testnet Stacks tokens -description: Set up and run a miner on the Stacks 2.0 testnet -sidebar_position: 4 +description: Set up and run a miner on Stacks Testnet +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 testnet. +For more on the technical details of mining, please review the [mining guide](../stacks-academy/mining) -If you want to learn more about the technical details of mining, please review the [mining guide](../understand-stacks/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)). -## Running bitcoind locally +If you're interested in mining on the Stacks mainnet, you can find instructions on how to do that [here](miner-mainnet): -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) +## Running a Bitcoin Testnet Full Node -First, download the bitcoind software for your platform from https://bitcoin.org/en/download. +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. -Next, start bitcoind with the following configuration: +- [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 -rpcuser=your-bitcoind-username -rpcpassword=your-bitcoind-password testnet=1 -txindex=0 -listen=1 -rpcserialversion=0 -maxorphantx=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 @@ -37,126 +54,51 @@ 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" -... +### Start Bitcoin -[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: +Finally, start bitcoind as follows: ```bash -stacks-node start --config=./testnet/stacks-node/conf/testnet-miner-conf.toml +bitcoind -conf=$HOME/bitcoin.conf ``` -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 -``` +:::note +It will take a few hours for the node to synchronize with Bitcoin testnet. +::: -The above code will compile an optimized binary. To use it, run: +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 -cd ../.. -./target/release/stacks-node start --config=./testnet/conf/testnet-follower-conf.toml +$ bitcoin-cli \ + -rpcconnect=localhost \ + -rpcport=18332 \ + -rpcuser=btcuser \ + -rpcpassword=btcpass \ +getblockchaininfo | jq .blocks +2417570 ``` -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 +## Running a Stacks Blockchain miner -### Prerequisites +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) -Make sure are [running a testnet node](run-a-node) before starting this tutorial. +_There may be some extra requirements to building, [defined here](https://github.com/stacksfoundation/miner-docs/blob/main/prerequisites.md#install-required-packages)_ -### Generate keychain and get testnet tokens in Windows +:::tip It is recommened to use a persistent location for the chainstate, in the steps below we're using `/stacks-blockchain` ::: -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. +### Generate a keychain -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. +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. -Generate a keychain: +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 -npm install --global @stacks/cli -stx make_keychain -t > cli_keychain.json -type cli_keychain.json +npx @stacks/cli make_keychain -t 2>/dev/null | jq -r ``` -After this runs, you'll probably see some installation logs, and at the end you should see some JSON that looks like this: +After this runs, you should see some JSON printed to the screen that looks like this: ```json { @@ -170,107 +112,110 @@ After this runs, you'll probably see some installation logs, and at the end you } ``` -:::tip Check out the [Stacks CLI reference](https://docs.hiro.so/references/stacks-cli) for more details ::: +:::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. -Request BTC from faucet: +### Update the Stacks Blockchain Configuration File -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. 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`. -### Update configuration file +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. -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). +Next, update the bitcoin configuration: -Update the following properties: +- **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] -... -seed = "replace-with-your-private-key" -local_peer_seed = "replace-with-your-private-key" -... +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] -... -# To mine on Testnet, you need to run bitcoind locally -# Details can be found in above section, 'Running bitcoind locally' +chain = "bitcoin" +mode = "xenon" peer_host = "127.0.0.1" -username = "" -password = "" -... +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 ``` -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 +### Start the Stacks Blockchain -To start your miner, run this in the command line: +To run your miner, run this in the command line: ```bash -stacks-node start --config=testnet/stacks-node/conf/testnet-miner-conf.toml +stacks-node start --config=$HOME/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 +### 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 -set RUST_BACKTRACE=full; -set STACKS_LOG_DEBUG=1; -stacks-node start --config=testnet-miner-conf.toml +STACKS_LOG_DEBUG=1 stacks-node start --config=$HOME/testnet-miner-conf.toml ``` -## Optional: Running with Docker +--- + +## Optional: Running a Stacks Blockchain miner with Docker -Alternatively, you can run the testnet node with Docker. +Alternatively, you can run a Stacks testnet miner with Docker. -:::warning Ensure you have [Docker](https://docs.docker.com/get-docker/) installed on your machine. ::: +:::caution Ensure you have [Docker](https://docs.docker.com/get-docker/) installed ::: -### Generate keychain and get testnet tokens +### Generate a Keychain and Get Some Tokens Generate a keychain: ```bash -docker run -i node:14-alpine npx @stacks/cli make_keychain -t 2>/dev/null +docker run -i node:14-alpine npx @stacks/cli make_keychain 2>/dev/null | jq -r ``` -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 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. -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 Stacks Blockchain Docker Configuration File -Update the following properties: +Use the steps oulined above to create the [configuration file](miner-testnet#update-the-stacks-blockchain-configuration-file) -```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 +### 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 ::: @@ -281,7 +226,8 @@ docker run -d \ --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" \ + -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 \ @@ -294,26 +240,22 @@ You can review the node logs with this command: 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). +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 on your machine: +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 testnet tokens - -Generate a keychain: - -```bash -docker run -i node:14-alpine npx @stacks/cli make_keychain -t 2>/dev/null -``` +### Generate keychain and get some tokens -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. +Use the steps [outlined above](miner-testnet#generate-a-keychain-and-get-some-tokens) ### Install the chart and run the miner @@ -324,7 +266,7 @@ 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.node.seed="replace-with-your-privateKey-from-generate-keychain-step" \ ``` You can review the node logs with this command: From ab8b43f52258b8f2a767d4f08e46fa92d5c816b6 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:48:40 +0100 Subject: [PATCH 0733/1444] New translations stacks-node-configuration.md (Hindi) --- .../stacks-node-configuration.md | 158 +++++++++++------- 1 file changed, 101 insertions(+), 57 deletions(-) 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 index 89af343dc6..cd216e7103 100644 --- 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 @@ -1,7 +1,7 @@ --- title: Stacks Node Configuration description: Configuration parameters and options for the stacks-node binary -sidebar_position: 6 +sidebar_position: 4 --- ## Usage @@ -10,97 +10,141 @@ sidebar_position: 6 stacks-node sub-command [--subcommand-option ] ``` -## Subcommands +### 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 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 -### mocknet +## Configuration File Options -Start a node based on a fast local setup emulating a burnchain. Ideal for smart contract development. +The Stacks Blockchain configuration file has multiple sections under which an option may be placed. -Example: +- [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) -```bash -stacks-node mocknet -``` +For reference, several configuration file examples are [available here](https://github.com/stacks-network/stacks-blockchain/tree/master/testnet/stacks-node/conf) -### krypton +- [Example mainnet follower configuration](./stacks-node-configuration#example-mainnet-follower-configuration) -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). +### node -Example: +Contains various configuration options for the stacks-node binary. -```bash -stacks-node krypton -``` +| 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. | -### testnet +### events_observer -Start a node that will join and stream blocks from the public testnet. +:::info This section is _optional_ and not required -Example: +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. -```bash -stacks-node testnet -``` +| 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. | | -### mainnet +### connection_options -Start a node that joins and streams blocks from the public mainnet. +:::info This section is _optional_ and not required. -Example: +However, if this section is added, **all** fields are required ::: -```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. +Specifies configuration options for others connecting to the stacks node. -#### Arguments +| 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 | -**--config**: relative or absolute path to the TOML config file. Required. +### burnchain -Example: +This section contains configuration options pertaining to the blockchain the stacks-node binds to on the backend for proof-of-transfer (BTC). -```bash -stacks-node start --config=/path/to/config.toml -``` +| 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` | -See [Configuration File Options](#configuration-file-options) for more information. +#### Mining -#### version +| 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`. | -Displays information about the current version and the release cycle. +### ustx_balance -Example: +- `mocknet`/`testnet` only -```bash -stacks-node version -``` +This section contains configuration options allocating microSTX per address in the genesis block -#### help +This section can repeat multiple times, but each section can only define a single address. -Displays a help message. +:::info This section is only required for the `testnet` and `mocknet` networks. -Example: +However, if this section is added, **all** fields are required ::: -```bash -stacks-node help -``` +| 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 | -## Configuration File Options +## Example Mainnet Follower Configuration -The TOML configuration file has multiple sections under which an option may be placed. +```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" -To see a list of example configurations, [please see this page](https://github.com/stacks-network/stacks-blockchain/tree/master/testnet/stacks-node/conf). +[burnchain] +chain = "bitcoin" +mode = "mainnet" +peer_host = "localhost" +username = "user" +password = "pass" +rpc_port = 8332 +peer_port = 8333 -### Section: node +[[events_observer]] +endpoint = "localhost:3700" +retry_count = 255 +events_keys = ["*"] +``` -Contains various configuration options pertaining to the stacks-node. -Example: + From e842b12a292190bef6d0a330d1c3311d3f62458a Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:48:41 +0100 Subject: [PATCH 0734/1444] New translations accounts.md (Hindi) --- .../current/stacks-academy/accounts.md | 215 ++++++++++++++++++ 1 file changed, 215 insertions(+) create mode 100644 i18n/hi/docusaurus-plugin-content-docs/current/stacks-academy/accounts.md diff --git a/i18n/hi/docusaurus-plugin-content-docs/current/stacks-academy/accounts.md b/i18n/hi/docusaurus-plugin-content-docs/current/stacks-academy/accounts.md new file mode 100644 index 0000000000..55d0165def --- /dev/null +++ b/i18n/hi/docusaurus-plugin-content-docs/current/stacks-academy/accounts.md @@ -0,0 +1,215 @@ +--- +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" + } + } + ] +} +``` From cd00cd612232075ae1a3f17b33fc18f2d8d5ef44 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:48:42 +0100 Subject: [PATCH 0735/1444] New translations microblocks.md (Hindi) --- .../current/stacks-academy/microblocks.md | 107 ++++++++++++++++++ 1 file changed, 107 insertions(+) create mode 100644 i18n/hi/docusaurus-plugin-content-docs/current/stacks-academy/microblocks.md diff --git a/i18n/hi/docusaurus-plugin-content-docs/current/stacks-academy/microblocks.md b/i18n/hi/docusaurus-plugin-content-docs/current/stacks-academy/microblocks.md new file mode 100644 index 0000000000..9310aa65be --- /dev/null +++ b/i18n/hi/docusaurus-plugin-content-docs/current/stacks-academy/microblocks.md @@ -0,0 +1,107 @@ +--- +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. + +[provides an endpoint]: https://docs.hiro.so/get-started/stacks-blockchain-api#nonce-handling +[microblocks_api]: https://docs.hiro.so/api#tag/Microblocks From e178a0070caa65b8c6b387a8e371ea6fb3d0cd51 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:48:42 +0100 Subject: [PATCH 0736/1444] New translations mining.md (Hindi) --- .../current/stacks-academy/mining.md | 84 +++++++++++++++++++ 1 file changed, 84 insertions(+) create mode 100644 i18n/hi/docusaurus-plugin-content-docs/current/stacks-academy/mining.md diff --git a/i18n/hi/docusaurus-plugin-content-docs/current/stacks-academy/mining.md b/i18n/hi/docusaurus-plugin-content-docs/current/stacks-academy/mining.md new file mode 100644 index 0000000000..e6e93e130a --- /dev/null +++ b/i18n/hi/docusaurus-plugin-content-docs/current/stacks-academy/mining.md @@ -0,0 +1,84 @@ +--- +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 From 0a15b0cc7e53157042a04d92dc4c5bbc55a52f1b Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:48:43 +0100 Subject: [PATCH 0737/1444] New translations network.md (Hindi) --- .../current/stacks-academy/network.md | 148 ++++++++++++++++++ 1 file changed, 148 insertions(+) create mode 100644 i18n/hi/docusaurus-plugin-content-docs/current/stacks-academy/network.md diff --git a/i18n/hi/docusaurus-plugin-content-docs/current/stacks-academy/network.md b/i18n/hi/docusaurus-plugin-content-docs/current/stacks-academy/network.md new file mode 100644 index 0000000000..a0dc623d97 --- /dev/null +++ b/i18n/hi/docusaurus-plugin-content-docs/current/stacks-academy/network.md @@ -0,0 +1,148 @@ +--- +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 +} +``` From c250b20a5b10a41deee2907640db5bae00fa72f7 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:48:44 +0100 Subject: [PATCH 0738/1444] New translations stacking.md (Hindi) --- .../current/stacks-academy/stacking.md | 151 ++++++++++++++++++ 1 file changed, 151 insertions(+) create mode 100644 i18n/hi/docusaurus-plugin-content-docs/current/stacks-academy/stacking.md diff --git a/i18n/hi/docusaurus-plugin-content-docs/current/stacks-academy/stacking.md b/i18n/hi/docusaurus-plugin-content-docs/current/stacks-academy/stacking.md new file mode 100644 index 0000000000..545f538ecb --- /dev/null +++ b/i18n/hi/docusaurus-plugin-content-docs/current/stacks-academy/stacking.md @@ -0,0 +1,151 @@ +--- +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. 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. + +![](/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 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 (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 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) From 2cdd68e28720eddabe251eb646e8987bca1274a2 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:48:45 +0100 Subject: [PATCH 0739/1444] New translations technical-specs.md (Hindi) --- .../current/stacks-academy/technical-specs.md | 79 +++++++++++++++++++ 1 file changed, 79 insertions(+) create mode 100644 i18n/hi/docusaurus-plugin-content-docs/current/stacks-academy/technical-specs.md diff --git a/i18n/hi/docusaurus-plugin-content-docs/current/stacks-academy/technical-specs.md b/i18n/hi/docusaurus-plugin-content-docs/current/stacks-academy/technical-specs.md new file mode 100644 index 0000000000..695f849e1a --- /dev/null +++ b/i18n/hi/docusaurus-plugin-content-docs/current/stacks-academy/technical-specs.md @@ -0,0 +1,79 @@ +--- +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). +- 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 whitepaper v2](https://www.youtube.com/watch?v=Wd-Bfe8Sn-Y). From db2db6d00789ee09721db3452e4ea1c2c1aca38c Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:48:46 +0100 Subject: [PATCH 0740/1444] New translations testnet.md (Hindi) --- .../current/stacks-academy/testnet.md | 35 +++++++++++++++++++ 1 file changed, 35 insertions(+) create mode 100644 i18n/hi/docusaurus-plugin-content-docs/current/stacks-academy/testnet.md diff --git a/i18n/hi/docusaurus-plugin-content-docs/current/stacks-academy/testnet.md b/i18n/hi/docusaurus-plugin-content-docs/current/stacks-academy/testnet.md new file mode 100644 index 0000000000..f8b9f03df2 --- /dev/null +++ b/i18n/hi/docusaurus-plugin-content-docs/current/stacks-academy/testnet.md @@ -0,0 +1,35 @@ +--- +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. + +### 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) From 5c922d0720f153c13d56c7dd8c4c06d7f653566e Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:48:47 +0100 Subject: [PATCH 0741/1444] New translations transactions.md (Hindi) --- .../current/stacks-academy/transactions.md | 40 +++++++++++++++++++ 1 file changed, 40 insertions(+) create mode 100644 i18n/hi/docusaurus-plugin-content-docs/current/stacks-academy/transactions.md diff --git a/i18n/hi/docusaurus-plugin-content-docs/current/stacks-academy/transactions.md b/i18n/hi/docusaurus-plugin-content-docs/current/stacks-academy/transactions.md new file mode 100644 index 0000000000..ba6b18f0f7 --- /dev/null +++ b/i18n/hi/docusaurus-plugin-content-docs/current/stacks-academy/transactions.md @@ -0,0 +1,40 @@ +--- +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). ::: From 90ee5e44ef824c171293df611c8021e71a2862df Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:48:48 +0100 Subject: [PATCH 0742/1444] New translations language-functions.md (Hindi) --- .../current/clarity/language-functions.md | 2028 +++++++++++++++++ 1 file changed, 2028 insertions(+) create mode 100644 i18n/hi/docusaurus-plugin-content-docs/current/clarity/language-functions.md diff --git a/i18n/hi/docusaurus-plugin-content-docs/current/clarity/language-functions.md b/i18n/hi/docusaurus-plugin-content-docs/current/clarity/language-functions.md new file mode 100644 index 0000000000..32989bba8e --- /dev/null +++ b/i18n/hi/docusaurus-plugin-content-docs/current/clarity/language-functions.md @@ -0,0 +1,2028 @@ +--- +title: Functions +description: See a detailed list of all functions for the Clarity language. +sidebar_position: 3 +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: + +#### 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-existent\"))))) ;; 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-existent\") ;; 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-existent\" })) ;; 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-existent\" }))) ;; 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-existent\" }))) ;; 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 \"Stacks\" '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 successfully 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_ transferred from another principal, but rather minted. + +If a non-positive amount is provided to mint, this function returns `(err 1)`. Otherwise, on successfully 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_ transferred 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 successfully 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 successfully 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)) +``` From be349e79385fb65d7fed140f000a482cb19199ed Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:48:49 +0100 Subject: [PATCH 0743/1444] New translations language-keywords.md (Hindi) --- .../current/clarity/language-keywords.md | 146 ++++++++++++++++++ 1 file changed, 146 insertions(+) create mode 100644 i18n/hi/docusaurus-plugin-content-docs/current/clarity/language-keywords.md diff --git a/i18n/hi/docusaurus-plugin-content-docs/current/clarity/language-keywords.md b/i18n/hi/docusaurus-plugin-content-docs/current/clarity/language-keywords.md new file mode 100644 index 0000000000..1aca5359c3 --- /dev/null +++ b/i18n/hi/docusaurus-plugin-content-docs/current/clarity/language-keywords.md @@ -0,0 +1,146 @@ +--- +title: Keywords +description: See a detailed list of all keywords for the Clarity language. +sidebar_position: 4 +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 +``` From 55beefda6ea460624f2647ce857a8b8bc11b3ac7 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:48:50 +0100 Subject: [PATCH 0744/1444] New translations language-types.md (Hindi) --- .../current/clarity/language-types.md | 25 +++++++++++++++++++ 1 file changed, 25 insertions(+) create mode 100644 i18n/hi/docusaurus-plugin-content-docs/current/clarity/language-types.md diff --git a/i18n/hi/docusaurus-plugin-content-docs/current/clarity/language-types.md b/i18n/hi/docusaurus-plugin-content-docs/current/clarity/language-types.md new file mode 100644 index 0000000000..0af4577dc9 --- /dev/null +++ b/i18n/hi/docusaurus-plugin-content-docs/current/clarity/language-types.md @@ -0,0 +1,25 @@ +--- +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. | From e714870b67f84717f9dc3f5756089e767ab922f6 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:48:52 +0100 Subject: [PATCH 0745/1444] New translations miner-costs-and-fees.md (Hindi) --- .../current/nodes-and-miners/miner-costs-and-fees.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) 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 index 40397a51e0..dd8ee721cc 100644 --- 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 @@ -8,7 +8,7 @@ sidebar_position: 8 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 @@ -22,3 +22,5 @@ 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). From 6e86931126c33b3fd1b450109f0495e00864044f Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:48:52 +0100 Subject: [PATCH 0746/1444] New translations verify-miner.md (Hindi) --- .../current/nodes-and-miners/verify-miner.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) 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 index 094e3f03a1..18e8dd3a48 100644 --- 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 @@ -7,7 +7,7 @@ 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 +$ 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 -``` \ No newline at end of file +``` From ed8fa3822b1e15dea61e75e9c996357cc3c2a7da Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:48:53 +0100 Subject: [PATCH 0747/1444] New translations stacks-blockchain-api.md (Hindi) --- .../stacks-academy/stacks-blockchain-api.md | 41 +++++++++++++++++++ 1 file changed, 41 insertions(+) create mode 100644 i18n/hi/docusaurus-plugin-content-docs/current/stacks-academy/stacks-blockchain-api.md diff --git a/i18n/hi/docusaurus-plugin-content-docs/current/stacks-academy/stacks-blockchain-api.md b/i18n/hi/docusaurus-plugin-content-docs/current/stacks-academy/stacks-blockchain-api.md new file mode 100644 index 0000000000..ad9bb1822e --- /dev/null +++ b/i18n/hi/docusaurus-plugin-content-docs/current/stacks-academy/stacks-blockchain-api.md @@ -0,0 +1,41 @@ +--- +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`. ::: From 25083bd8f7fb2a434b59884bb1ced2bbdf613a5c Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:48:54 +0100 Subject: [PATCH 0748/1444] New translations run-a-node.md (Hindi) --- .../current/nodes-and-miners/run-a-node.md | 329 +++--------------- 1 file changed, 42 insertions(+), 287 deletions(-) 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 index 94d938c5ca..2993568ce4 100644 --- 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 @@ -1,5 +1,5 @@ --- -title: Run a node +title: Run a Node with Docker description: Set up and run a Stacks node sidebar_position: 1 tags: @@ -8,344 +8,99 @@ tags: ## Stacks Blockchain with Docker -Run your own Stacks Blockchain node easily with just few commands. +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) -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](./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) -## **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 -``` +## **Requirements:** -- With optional proxy: +The **minimum viable requirements** are listed below. -```bash -./manage.sh -n -a start -f proxy -``` +While you _can_ run a node using these specs, it's _recommended_ to assign more than the minimum for better performance. -- With optional bitcoin node: +- ⚠️ [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_ ) -```bash -./manage.sh -n -a start -f bitcoin -``` +:::caution MacOS with an ARM processor is NOT recommended -5. **Stop the Services** +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. ::: -```bash -./manage.sh -n -a stop -``` - -6. **Retrieve Service Logs** - -```bash -./manage.sh -n -a logs -``` - -- Export docker log files to `./exported-logs`: +## **Quickstart** -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. +The `` placeholder used below can be replaced with one of: -```bash -./manage.sh -n -a logs export -``` +- mainnet +- testnet +- mocknet -7. **Restart all services** +1. **Clone the stacks-blockchain-docker repository locally** ```bash -./manage.sh -n -a restart +git clone https://github.com/stacks-network/stacks-blockchain-docker && cd stacks-blockchain-docker ``` -- With optional proxy: +2. **Start the Services** ```bash -./manage.sh -n -a restart -f proxy +./manage.sh -n -a start ``` -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. +:::note With an optional HTTP proxy on port 80: ```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. - +./manage.sh -n -a start -f proxy ``` -9. **Download BNS data to** `./persistent-data/bns-data` - -```bash -./manage.sh bns -``` +::: -10. **Export stacks-blockchain-api events** (_Not applicable for mocknet_) +## **Accessing the services** -```bash -./manage.sh -n -a export -# check logs for completion -./manage.sh -n -a restart -``` +:::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. -11. **Replay stacks-blockchain-api events** (_Not applicable for mocknet_) +Follow the logs to track the sync progress: ```bash -./manage.sh -n -a import -# check logs for completion -./manage.sh -n -a restart +./manage.sh -n -a logs ``` -## **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` +- Ports `20443-20444` are exposed on `localhost` ```bash -curl -sL localhost:20443/v2/info | jq +curl -sL localhost:20443/v2/info | jq -r ``` **stacks-blockchain-api**: -- Port `3999` are exposed to `localhost` +- Port `3999` is exposed on `localhost` ```bash -curl -sL localhost:3999/v2/info | jq +curl -sL localhost:3999 | jq -r ``` **proxy**: -- Port `80` is exposed to `localhost` +- Port `80` is exposed on `localhost` ```bash -curl -sL localhost/v2/info | jq -curl -sL localhost/ | jq +curl -sL localhost/v2/info | jq -r +curl -sL localhost | jq -r ``` --- ## 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 -``` +:::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): ::: --- - -## **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 From 31cc05122fb71967119a7d80cf22569d07c20623 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:48:55 +0100 Subject: [PATCH 0749/1444] New translations index.md (Hindi) --- .../current/clarity/index.md | 58 +++++++++++++++++++ 1 file changed, 58 insertions(+) create mode 100644 i18n/hi/docusaurus-plugin-content-docs/current/clarity/index.md diff --git a/i18n/hi/docusaurus-plugin-content-docs/current/clarity/index.md b/i18n/hi/docusaurus-plugin-content-docs/current/clarity/index.md new file mode 100644 index 0000000000..903de93a45 --- /dev/null +++ b/i18n/hi/docusaurus-plugin-content-docs/current/clarity/index.md @@ -0,0 +1,58 @@ +--- +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?2 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. If you are unsure what this means, let it not worry you for now. The serious advantage of decidability will become more apparent over time. + +### 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. From 767f4a7c6789e1b581c7882122ceee1470e2636a Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:48:56 +0100 Subject: [PATCH 0750/1444] New translations index.md (Hindi) --- .../current/stacks-academy/index.md | 11 +++++++++++ 1 file changed, 11 insertions(+) create mode 100644 i18n/hi/docusaurus-plugin-content-docs/current/stacks-academy/index.md diff --git a/i18n/hi/docusaurus-plugin-content-docs/current/stacks-academy/index.md b/i18n/hi/docusaurus-plugin-content-docs/current/stacks-academy/index.md new file mode 100644 index 0000000000..a5bdb3c790 --- /dev/null +++ b/i18n/hi/docusaurus-plugin-content-docs/current/stacks-academy/index.md @@ -0,0 +1,11 @@ +--- +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. From 57d357d4db3114df3a9fb4c319d3f9f7af47a457 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:48:56 +0100 Subject: [PATCH 0751/1444] New translations proof-of-transfer.md (Hindi) --- .../stacks-academy/proof-of-transfer.md | 83 +++++++++++++++++++ 1 file changed, 83 insertions(+) create mode 100644 i18n/hi/docusaurus-plugin-content-docs/current/stacks-academy/proof-of-transfer.md diff --git a/i18n/hi/docusaurus-plugin-content-docs/current/stacks-academy/proof-of-transfer.md b/i18n/hi/docusaurus-plugin-content-docs/current/stacks-academy/proof-of-transfer.md new file mode 100644 index 0000000000..50f4b739d6 --- /dev/null +++ b/i18n/hi/docusaurus-plugin-content-docs/current/stacks-academy/proof-of-transfer.md @@ -0,0 +1,83 @@ +--- +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. From c7b6c4d17d65e2b068ea1e27db6f8f2b0570d9a2 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:48:57 +0100 Subject: [PATCH 0752/1444] New translations what-is-stacks.md (Hindi) --- .../current/stacks-academy/what-is-stacks.md | 102 ++++++++++++++++++ 1 file changed, 102 insertions(+) create mode 100644 i18n/hi/docusaurus-plugin-content-docs/current/stacks-academy/what-is-stacks.md diff --git a/i18n/hi/docusaurus-plugin-content-docs/current/stacks-academy/what-is-stacks.md b/i18n/hi/docusaurus-plugin-content-docs/current/stacks-academy/what-is-stacks.md new file mode 100644 index 0000000000..94277da8a9 --- /dev/null +++ b/i18n/hi/docusaurus-plugin-content-docs/current/stacks-academy/what-is-stacks.md @@ -0,0 +1,102 @@ +--- +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. + +There's a lot of jargon, possible assumptions, controversy, and cool technology wrapped up in those statements. So let's get started by getting a 30,000 foot view of what exactly Stacks is. + +## Stacks Explained in (Slightly Less Than) 10 Minutes + +
+ +
+ +## 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, Stacks takes a different approach. + +## 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). + +By taking this 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 with some unique properties, like having its own token, that allow it to maintain a historical ledger of all of its transactions and operate with its own security budget. + +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_. + +Nope. 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. From 52013884d09ffa67dc720e63439fe8bb3846a19b Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:48:58 +0100 Subject: [PATCH 0753/1444] New translations community-tutorials.md (Hindi) --- .../current/tutorials/community-tutorials.md | 24 +++++++++++++++++++ 1 file changed, 24 insertions(+) create mode 100644 i18n/hi/docusaurus-plugin-content-docs/current/tutorials/community-tutorials.md diff --git a/i18n/hi/docusaurus-plugin-content-docs/current/tutorials/community-tutorials.md b/i18n/hi/docusaurus-plugin-content-docs/current/tutorials/community-tutorials.md new file mode 100644 index 0000000000..a4f3d970ca --- /dev/null +++ b/i18n/hi/docusaurus-plugin-content-docs/current/tutorials/community-tutorials.md @@ -0,0 +1,24 @@ +--- +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/) From 5a266fb6bd34ac5589ceeb3a90502862937ff94f Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:48:59 +0100 Subject: [PATCH 0754/1444] New translations hello-stacks.md (Hindi) --- .../current/tutorials/hello-stacks.md | 759 ++++++++++++++++++ 1 file changed, 759 insertions(+) create mode 100644 i18n/hi/docusaurus-plugin-content-docs/current/tutorials/hello-stacks.md diff --git a/i18n/hi/docusaurus-plugin-content-docs/current/tutorials/hello-stacks.md b/i18n/hi/docusaurus-plugin-content-docs/current/tutorials/hello-stacks.md new file mode 100644 index 0000000000..a0a442d135 --- /dev/null +++ b/i18n/hi/docusaurus-plugin-content-docs/current/tutorials/hello-stacks.md @@ -0,0 +1,759 @@ +--- +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. From 75fe030e4a18819eec08be0941cbd2417543f1d8 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:49:00 +0100 Subject: [PATCH 0755/1444] New translations index.md (Hindi) --- .../current/tutorials/index.md | 11 +++++++++++ 1 file changed, 11 insertions(+) create mode 100644 i18n/hi/docusaurus-plugin-content-docs/current/tutorials/index.md diff --git a/i18n/hi/docusaurus-plugin-content-docs/current/tutorials/index.md b/i18n/hi/docusaurus-plugin-content-docs/current/tutorials/index.md new file mode 100644 index 0000000000..1d544c7bc1 --- /dev/null +++ b/i18n/hi/docusaurus-plugin-content-docs/current/tutorials/index.md @@ -0,0 +1,11 @@ +--- +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. From 4870f61ab51cabd4bf81e5294e819c63ac4dabdc Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:49:01 +0100 Subject: [PATCH 0756/1444] New translations satoshis-ridge.md (Hindi) --- .../current/tutorials/satoshis-ridge.md | 75 +++++++++++++++++++ 1 file changed, 75 insertions(+) create mode 100644 i18n/hi/docusaurus-plugin-content-docs/current/tutorials/satoshis-ridge.md diff --git a/i18n/hi/docusaurus-plugin-content-docs/current/tutorials/satoshis-ridge.md b/i18n/hi/docusaurus-plugin-content-docs/current/tutorials/satoshis-ridge.md new file mode 100644 index 0000000000..596339ae74 --- /dev/null +++ b/i18n/hi/docusaurus-plugin-content-docs/current/tutorials/satoshis-ridge.md @@ -0,0 +1,75 @@ +--- +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 arguable one of its strengths. + +Instead, we need to create separate layers that add additional functionality without modify 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. From dce425500093c42e54d6c6dc9c223dfa573714d7 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:49:02 +0100 Subject: [PATCH 0757/1444] New translations crash-course.md (Hindi) --- .../current/clarity/crash-course.md | 122 ++++++++++++++++++ 1 file changed, 122 insertions(+) create mode 100644 i18n/hi/docusaurus-plugin-content-docs/current/clarity/crash-course.md diff --git a/i18n/hi/docusaurus-plugin-content-docs/current/clarity/crash-course.md b/i18n/hi/docusaurus-plugin-content-docs/current/clarity/crash-course.md new file mode 100644 index 0000000000..5b27a3c275 --- /dev/null +++ b/i18n/hi/docusaurus-plugin-content-docs/current/clarity/crash-course.md @@ -0,0 +1,122 @@ +--- +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.md). + +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. + +```clojure +(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: + +```clojure +(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. From 2efe5566b4c82a4408e072fa9bebe637df84cfee Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:49:02 +0100 Subject: [PATCH 0758/1444] New translations sample-contracts.md (Hindi) --- .../current/clarity/sample-contracts.md | 14 ++++++++++++++ 1 file changed, 14 insertions(+) create mode 100644 i18n/hi/docusaurus-plugin-content-docs/current/clarity/sample-contracts.md diff --git a/i18n/hi/docusaurus-plugin-content-docs/current/clarity/sample-contracts.md b/i18n/hi/docusaurus-plugin-content-docs/current/clarity/sample-contracts.md new file mode 100644 index 0000000000..adb12a58fd --- /dev/null +++ b/i18n/hi/docusaurus-plugin-content-docs/current/clarity/sample-contracts.md @@ -0,0 +1,14 @@ +--- +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) From cd2c81923956f8d710dc7c1d4cd993f3af8eeaf1 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:49:03 +0100 Subject: [PATCH 0759/1444] New translations index.md (Hindi) --- .../current/cookbook/index.md | 64 +++++++++++++++++++ 1 file changed, 64 insertions(+) create mode 100644 i18n/hi/docusaurus-plugin-content-docs/current/cookbook/index.md diff --git a/i18n/hi/docusaurus-plugin-content-docs/current/cookbook/index.md b/i18n/hi/docusaurus-plugin-content-docs/current/cookbook/index.md new file mode 100644 index 0000000000..a2b0e42eea --- /dev/null +++ b/i18n/hi/docusaurus-plugin-content-docs/current/cookbook/index.md @@ -0,0 +1,64 @@ +--- +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 + +Swapping between Bitcoin and Stacks addresses + +Swapping between xBTC and BTC + +Verifying a transaction on the BTC chain + +## 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 + +Airdropping an NFT to a Bitcoin address + +## Stacking and Mining + +Simple stacking pool + +Continuous stacking + +Simple mining pool + +Proof of PoX payout + +## Oracles + +Creating a simple BTC price oracle + +## Frontend + +[Post conditions with Stacks.js](./post-conditions) + +[Authentication with Stacks.js](./stacks-js-auth) + +[Sending transactions with Stacks.js](./stacks-js-sending-transactions) + +## Complete Apps + +[Sup](https://github.com/kenrogers/sup) + +[Hello Stacks](https://github.com/kenrogers/hello-stacks) From 2410cd234bd48b3f38a44f15c08eba26b905b53d Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:49:04 +0100 Subject: [PATCH 0760/1444] New translations btc-connection.md (Hindi) --- .../current/stacks-academy/btc-connection.md | 196 ++++++++++++++++++ 1 file changed, 196 insertions(+) create mode 100644 i18n/hi/docusaurus-plugin-content-docs/current/stacks-academy/btc-connection.md diff --git a/i18n/hi/docusaurus-plugin-content-docs/current/stacks-academy/btc-connection.md b/i18n/hi/docusaurus-plugin-content-docs/current/stacks-academy/btc-connection.md new file mode 100644 index 0000000000..b4db915969 --- /dev/null +++ b/i18n/hi/docusaurus-plugin-content-docs/current/stacks-academy/btc-connection.md @@ -0,0 +1,196 @@ +--- +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. + +## Stacks Among Other Bitcoin Layers + +In the [last section](./what-is-stacks.md) we covered what Stacks actually is and what problem it is solving, but this is not a new problem. The Bitcoin write problem has been a bit of a holy grail problem in the crypto world for a while now. + +Bitcoin is the OG cryptocurrency and has the largest market cap, but it also some of the least functionality, which means if we want to make it a productive asset and use it to build a decentralized economy, we need to take a layered approach and let Bitcoin do what it does best, while creating additional layers on top of it to add functionality. + +So how does Stacks compare to some of the other approaches to layering on top of Bitcoin? + +### 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. + +## 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. + +But because it has its own execution environment and smart contract state to maintain, it needs a token to incentivize maintenance of the network. + +But it goes further than that. It is possible to build a system like this without a token using something like merge-mining or a sidechain, but then we lose out on the additional benefit of having the chain state's safety underpinned by its entire token economy's value. + +In the case of Stacks, the safety and liveness of the chain are underpinned by this value, and the stacking mechanism incentivizes network members to increase this value. + +From Jude Nelson, Stacks core developer: + +"How hard is it to cause a safety failure (i.e. a double-spend via a reorg) on just the canonical Stacks chain fork? Anyone can become a miner by spending BTC, so without loss of generality, reverting the last block on the canonical chain is at least as hard in expectation as spending more BTC than the rest of the miners combined for that block. Because each Bitcoin block selects at most one Stacks block, the act of reorging the canonical Stacks chain back N blocks is the act of winning at least N + 1 blocks built off of a common ancestor that is N blocks deep. This is a lower bound on the number of Bitcoin blocks mined during which a reorg needs to take place — in practice, honest miners will keep working on the canonical chain, and will win some Stacks blocks of their own, which in turn increases the number of Stacks blocks the reorging miners must win. + +How costly is it to carry out a reorg of N blocks? It’s a function of how valuable STX is relative to BTC — the more valuable STX are, the more BTC honest miners are committing to mining (this has borne out in practice), and thus the more BTC a reorging miner must commit. Therefore, the cost of a reorg is a function of the value of STX. + +This is similar to the economic security of a PoW blockchain. Like in PoW, each fork of the Stacks chain has its own independent “security budget” — an attacker must out-spend the security budget to carry out a reorg, and the security budget is a function of the block rewards. In PoX, the only difference is that the miners spend another blockchain’s tokens (BTC in Stacks’ case) instead of energy. Therefore, Stacks can’t be a sidechain, a drivechain, or a merge-mined chain, because none of these other systems’ security budgets are a function of their tokens’ worth. Sidechains, drivechains, and merged-mined chains all rely on external miners for their safety, since their safety is guaranteed in part by external miners validating their blocks. The onus on these systems is to get external miners to care enough to do so, and in the case of sidechains, drivechains, and blind merged-mined chains, there is an additional onus to encourage their nodes to mine blocks at all (since there is no on-chain reward for them to earn by doing so). By contrast, disinterested Bitcoin miners neither assist nor prevent a reorg in PoX — they only record the history of all Stacks forks. + +PoX offers two additional, unique security properties on top of PoW. First, no matter how much BTC a reorging miner can commit, the act of executing a reorg is going to be time-consuming. Unless the attacker can attack the Bitcoin chain itself by quickly producing a better Bitcoin fork, a reorging miner must sustain the attack for at least N + 1 Bitcoin blocks. This gives honest miners and users ample time to notice and react to the reorg attempt. + +Second, the history of block production in all Stacks forks is embedded within Bitcoin. This allows the system to leverage Bitcoin’s security budget in order to ensure that all forks are public. This is because the act of producing a hidden Stacks fork, where the fork’s block hashes are not known to the honest miners, is the act of producing a hidden canonical Bitcoin fork. Therefore, the act of producing a hidden Stacks fork is at least as hard as reorging the Bitcoin chain. A PoX chain leverages this property not to prevent reorgs, but to make reorgs unprofitable. + +By anchoring blocks to an existing blockchain, a PoX chain forces reorgs to happen out in the open, thereby giving advance warning to all honest network participants when they happen. Honest miners, users, and exchanges will see the PoX transactions for reorg attempts on the existing blockchain, and adapt their behaviors accordingly: honest miners will increase their commitments, and users and exchanges will require more confirmations for transactions. This makes the act of carrying out a reorg while also making a profit much more challenging, since malicious reorgs — like selfish mining and double-spending — rely on secrecy to work effectively. Specific to Stacks, miners are additionally required to mine for a “warm-up” period of two blocks, during which they must spend BTC at their target commit levels but will not win any Stacks blocks. So, a high-budget reorg attempt will not only be costly, but will also alert the rest of the network before the damage is done." + +- [What Kind of Blockchain is Stacks?](https://stacks.org/stacks-blockchain) + +## 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) From 335fa8d4fe3c09c7797e380abeaada5e50011346 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:49:05 +0100 Subject: [PATCH 0761/1444] New translations post-conditions.md (Hindi) --- .../current/stacks-academy/post-conditions.md | 39 +++++++++++++++++++ 1 file changed, 39 insertions(+) create mode 100644 i18n/hi/docusaurus-plugin-content-docs/current/stacks-academy/post-conditions.md diff --git a/i18n/hi/docusaurus-plugin-content-docs/current/stacks-academy/post-conditions.md b/i18n/hi/docusaurus-plugin-content-docs/current/stacks-academy/post-conditions.md new file mode 100644 index 0000000000..bb0727194f --- /dev/null +++ b/i18n/hi/docusaurus-plugin-content-docs/current/stacks-academy/post-conditions.md @@ -0,0 +1,39 @@ +--- +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). From 7516d7a3692d2a1206ca8c3a8e203e344bf62823 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:49:06 +0100 Subject: [PATCH 0762/1444] New translations creating-an-ft.md (Hindi) --- .../current/cookbook/creating-an-ft.md | 99 +++++++++++++++++++ 1 file changed, 99 insertions(+) create mode 100644 i18n/hi/docusaurus-plugin-content-docs/current/cookbook/creating-an-ft.md diff --git a/i18n/hi/docusaurus-plugin-content-docs/current/cookbook/creating-an-ft.md b/i18n/hi/docusaurus-plugin-content-docs/current/cookbook/creating-an-ft.md new file mode 100644 index 0000000000..4e3bad99d2 --- /dev/null +++ b/i18n/hi/docusaurus-plugin-content-docs/current/cookbook/creating-an-ft.md @@ -0,0 +1,99 @@ +--- +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) + ) +) +``` From a57303d160b16a51f4e9eae5115503cdfb73126e Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:49:06 +0100 Subject: [PATCH 0763/1444] New translations creating-an-nft.md (Hindi) --- .../current/cookbook/creating-an-nft.md | 87 +++++++++++++++++++ 1 file changed, 87 insertions(+) create mode 100644 i18n/hi/docusaurus-plugin-content-docs/current/cookbook/creating-an-nft.md diff --git a/i18n/hi/docusaurus-plugin-content-docs/current/cookbook/creating-an-nft.md b/i18n/hi/docusaurus-plugin-content-docs/current/cookbook/creating-an-nft.md new file mode 100644 index 0000000000..08faf9393a --- /dev/null +++ b/i18n/hi/docusaurus-plugin-content-docs/current/cookbook/creating-an-nft.md @@ -0,0 +1,87 @@ +--- +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 +Code for this recipe has been pulled from [this NFT tutorial](https://blog.developerdao.com/building-an-nft-with-stacks-and-clarity) from Developer DAO. +::: + +## 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) + ) +) +``` From 571b4c4a879efff5d05a610b4a79306138085866 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:49:07 +0100 Subject: [PATCH 0764/1444] New translations post-conditions.md (Hindi) --- .../current/cookbook/post-conditions.md | 136 ++++++++++++++++++ 1 file changed, 136 insertions(+) create mode 100644 i18n/hi/docusaurus-plugin-content-docs/current/cookbook/post-conditions.md diff --git a/i18n/hi/docusaurus-plugin-content-docs/current/cookbook/post-conditions.md b/i18n/hi/docusaurus-plugin-content-docs/current/cookbook/post-conditions.md new file mode 100644 index 0000000000..571fc20d48 --- /dev/null +++ b/i18n/hi/docusaurus-plugin-content-docs/current/cookbook/post-conditions.md @@ -0,0 +1,136 @@ +--- +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. From 78647f0ae4132aa9724febdff58b915352450b4f Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:49:08 +0100 Subject: [PATCH 0765/1444] New translations stacks-js-auth.md (Hindi) --- .../current/cookbook/stacks-js-auth.md | 98 +++++++++++++++++++ 1 file changed, 98 insertions(+) create mode 100644 i18n/hi/docusaurus-plugin-content-docs/current/cookbook/stacks-js-auth.md diff --git a/i18n/hi/docusaurus-plugin-content-docs/current/cookbook/stacks-js-auth.md b/i18n/hi/docusaurus-plugin-content-docs/current/cookbook/stacks-js-auth.md new file mode 100644 index 0000000000..89d1f06e00 --- /dev/null +++ b/i18n/hi/docusaurus-plugin-content-docs/current/cookbook/stacks-js-auth.md @@ -0,0 +1,98 @@ +--- +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 && ( + + ); +} +``` From d76e1a9a5d5b9cbcecc9442f12539ca01b34b063 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:49:09 +0100 Subject: [PATCH 0766/1444] New translations stacks-js-sending-transactions.md (Hindi) --- .../stacks-js-sending-transactions.md | 55 +++++++++++++++++++ 1 file changed, 55 insertions(+) create mode 100644 i18n/hi/docusaurus-plugin-content-docs/current/cookbook/stacks-js-sending-transactions.md diff --git a/i18n/hi/docusaurus-plugin-content-docs/current/cookbook/stacks-js-sending-transactions.md b/i18n/hi/docusaurus-plugin-content-docs/current/cookbook/stacks-js-sending-transactions.md new file mode 100644 index 0000000000..849c7d1f42 --- /dev/null +++ b/i18n/hi/docusaurus-plugin-content-docs/current/cookbook/stacks-js-sending-transactions.md @@ -0,0 +1,55 @@ +--- +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. From 6370d6e91e2dd9aaaa05f49993301074949a9911 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:49:10 +0100 Subject: [PATCH 0767/1444] New translations _category_.json (Hindi) --- .../current/clarity/noteworthy-contracts/_category_.json | 8 ++++++++ 1 file changed, 8 insertions(+) create mode 100644 i18n/hi/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/_category_.json diff --git a/i18n/hi/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/_category_.json b/i18n/hi/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/_category_.json new file mode 100644 index 0000000000..f5de305558 --- /dev/null +++ b/i18n/hi/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/_category_.json @@ -0,0 +1,8 @@ +{ + "label": "Noteworthy Contracts", + "position": 4, + "link": { + "type": "generated-index", + "description": "Specific deployed Clarity Contracts worth mentioning." + } +} \ No newline at end of file From d95e77c645e7a46eba837ec22b835afd48acce98 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:49:11 +0100 Subject: [PATCH 0768/1444] New translations bns-contract.md (Hindi) --- .../noteworthy-contracts/bns-contract.md | 519 ++++++++++++++++++ 1 file changed, 519 insertions(+) create mode 100644 i18n/hi/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/bns-contract.md diff --git a/i18n/hi/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/bns-contract.md b/i18n/hi/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/bns-contract.md new file mode 100644 index 0000000000..a7770b7d24 --- /dev/null +++ b/i18n/hi/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/bns-contract.md @@ -0,0 +1,519 @@ +--- +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 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` From a9c6637cae570aa55bd6f3e14d2460dd5fe42612 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:49:12 +0100 Subject: [PATCH 0769/1444] New translations xbtc.md (Hindi) --- .../clarity/noteworthy-contracts/xbtc.md | 28 +++++++++++++++++++ 1 file changed, 28 insertions(+) create mode 100644 i18n/hi/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/xbtc.md diff --git a/i18n/hi/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/xbtc.md b/i18n/hi/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/xbtc.md new file mode 100644 index 0000000000..e535dcf260 --- /dev/null +++ b/i18n/hi/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/xbtc.md @@ -0,0 +1,28 @@ +--- +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) From 378cee61e94818e99f7503974916cc462fc5b9db Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:49:13 +0100 Subject: [PATCH 0770/1444] New translations index.md (Hindi) --- .../current/glossary/index.md | 284 ++++++++++++++++++ 1 file changed, 284 insertions(+) create mode 100644 i18n/hi/docusaurus-plugin-content-docs/current/glossary/index.md diff --git a/i18n/hi/docusaurus-plugin-content-docs/current/glossary/index.md b/i18n/hi/docusaurus-plugin-content-docs/current/glossary/index.md new file mode 100644 index 0000000000..419c0e0d73 --- /dev/null +++ b/i18n/hi/docusaurus-plugin-content-docs/current/glossary/index.md @@ -0,0 +1,284 @@ +--- +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. From ff52782b09427f099f266b750b846beb08cea70c Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:49:13 +0100 Subject: [PATCH 0771/1444] New translations quicknode.md (Hindi) --- .../current/nodes-and-miners/quicknode.md | 45 +++++++++++++++++++ 1 file changed, 45 insertions(+) create mode 100644 i18n/hi/docusaurus-plugin-content-docs/current/nodes-and-miners/quicknode.md diff --git a/i18n/hi/docusaurus-plugin-content-docs/current/nodes-and-miners/quicknode.md b/i18n/hi/docusaurus-plugin-content-docs/current/nodes-and-miners/quicknode.md new file mode 100644 index 0000000000..1281964689 --- /dev/null +++ b/i18n/hi/docusaurus-plugin-content-docs/current/nodes-and-miners/quicknode.md @@ -0,0 +1,45 @@ +--- +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. From 93aa319f03654197af61892f68db62f3c8e266a7 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:49:14 +0100 Subject: [PATCH 0772/1444] New translations defi.md (Hindi) --- .../current/services-using-stacks/defi.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) 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 index 51defacba7..58717a3234 100644 --- 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 @@ -26,7 +26,7 @@ Please edit this page to add any relevant new site that we are missing. ## Lnswap -[LNSWAP](https://www.lnswap.org). Non custiodial crypto currency exchange +[LNSWAP](https://www.lnswap.org). Non-custodial crypto currency exchange ![](/img/sh_lnswap.png) @@ -41,4 +41,3 @@ Please edit this page to add any relevant new site that we are missing. [Stackswap](https://app.stackswap.org/v2) ![](/img/sh_stackswap.png) - From 37df4132b5ae3125691a26e233e911d16c09557b Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:49:15 +0100 Subject: [PATCH 0773/1444] New translations more.md (Hindi) --- .../current/services-using-stacks/more.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) 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 index df0b3e2254..1e14b9a5a5 100644 --- 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 @@ -18,6 +18,6 @@ Please edit this page to add any relevant new site that we are missing. ## Sigle -[Sigle](https://www.sigle.io/) is a decentralised and open source web 3 writing platform. +[Sigle](https://www.sigle.io/) is a decentralized and open source web 3 writing platform. -![](/img/sh_sigle.png) \ No newline at end of file +![](/img/sh_sigle.png) From 18abdc2fe96b16ee449046904c34bae4add88710 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:49:16 +0100 Subject: [PATCH 0774/1444] New translations nft.md (Hindi) --- .../current/services-using-stacks/nft.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) 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 index abb770663c..d582604854 100644 --- 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 @@ -15,6 +15,7 @@ Please edit this page to add any relevant new site that we are missing. ![website-screenshot](/img/sh_nft_byzantion.png) ### [Gamma](https://gamma.io/) + ![website-screenshot](/img/sh_nft_gamma.png) ### [Megapont](https://www.megapont.com/) @@ -35,4 +36,4 @@ Please edit this page to add any relevant new site that we are missing. ### [Superfandom](https://superfandom.io/) -![website-screenshot](/img/sh_superfandom.png) \ No newline at end of file +![website-screenshot](/img/sh_superfandom.png) From e5ebf950bf1090b09f99f91c11bff41eab01601c Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:49:17 +0100 Subject: [PATCH 0775/1444] New translations stacks-info-sites.md (Hindi) --- .../current/services-using-stacks/stacks-info-sites.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) 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 index 35ced8dac6..54f6823e33 100644 --- 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 @@ -30,7 +30,7 @@ Please edit this page to add any relevant new site that we are missing. ![website-screenshot](/img/sh_stxstats.png) -### [Novuminsights](https://stacks.novuminsights.com/health) +### [Novum Insights](https://stacks.novuminsights.com/health) ![website-screenshot](/img/sh_novuminsights.png) From 4950cd8556e3f0fce2fc227d47bb37c94053c054 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:49:18 +0100 Subject: [PATCH 0776/1444] New translations wallets.md (Hindi) --- .../current/services-using-stacks/wallets.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) 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 index e5ea6c5b45..2d3fcc85f2 100644 --- 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 @@ -15,6 +15,7 @@ Please edit this page to add any relevant new site that we are missing. [Blockchain.com](https://www.blockchain.com/wallet) ![](/img/sh_blockchain.png) + ## Boom [Boom](https://boom.money) @@ -26,6 +27,7 @@ Please edit this page to add any relevant new site that we are missing. [D'CENT](https://dcentwallet.com) ![](/img/sh_dcent.png) + ## Hiro Wallet [Hiro Wallet](https://www.hiro.so/wallet) @@ -48,4 +50,4 @@ Please edit this page to add any relevant new site that we are missing. [Wise](https://wiseapp.id) -![](/img/sh_wiseapp.png) \ No newline at end of file +![](/img/sh_wiseapp.png) From 7bf9332dc9f879336d644d3dc43a91fd661d9c49 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:49:18 +0100 Subject: [PATCH 0777/1444] New translations whitepapers.md (Hindi) --- .../current/stacks-academy/whitepapers.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) create mode 100644 i18n/hi/docusaurus-plugin-content-docs/current/stacks-academy/whitepapers.md diff --git a/i18n/hi/docusaurus-plugin-content-docs/current/stacks-academy/whitepapers.md b/i18n/hi/docusaurus-plugin-content-docs/current/stacks-academy/whitepapers.md new file mode 100644 index 0000000000..0e564fbf44 --- /dev/null +++ b/i18n/hi/docusaurus-plugin-content-docs/current/stacks-academy/whitepapers.md @@ -0,0 +1,12 @@ +--- +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) From e533c70f4140353700282e94c1804148a40f921a Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:49:19 +0100 Subject: [PATCH 0778/1444] New translations stacking-contract.md (Hindi) --- .../noteworthy-contracts/stacking-contract.md | 352 ++++++++++++++++++ 1 file changed, 352 insertions(+) create mode 100644 i18n/hi/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/stacking-contract.md diff --git a/i18n/hi/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/stacking-contract.md b/i18n/hi/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/stacking-contract.md new file mode 100644 index 0000000000..c0027256cd --- /dev/null +++ b/i18n/hi/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/stacking-contract.md @@ -0,0 +1,352 @@ +--- +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. 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` From cb14100e23012d5cf5fa7c6f0e94718de7d38af3 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:49:20 +0100 Subject: [PATCH 0779/1444] New translations index.md (Hindi) --- .../current/next-steps/index.md | 39 +++++++++++++++++++ 1 file changed, 39 insertions(+) create mode 100644 i18n/hi/docusaurus-plugin-content-docs/current/next-steps/index.md diff --git a/i18n/hi/docusaurus-plugin-content-docs/current/next-steps/index.md b/i18n/hi/docusaurus-plugin-content-docs/current/next-steps/index.md new file mode 100644 index 0000000000..00ddec9178 --- /dev/null +++ b/i18n/hi/docusaurus-plugin-content-docs/current/next-steps/index.md @@ -0,0 +1,39 @@ +--- +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) From 4525e22d85e0dc0c4cd70b92e6bb27a198a26898 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:49:21 +0100 Subject: [PATCH 0780/1444] New translations sips.md (Hindi) --- .../current/stacks-academy/sips.md | 52 +++++++++++++++++++ 1 file changed, 52 insertions(+) create mode 100644 i18n/hi/docusaurus-plugin-content-docs/current/stacks-academy/sips.md diff --git a/i18n/hi/docusaurus-plugin-content-docs/current/stacks-academy/sips.md b/i18n/hi/docusaurus-plugin-content-docs/current/stacks-academy/sips.md new file mode 100644 index 0000000000..aa2db18e62 --- /dev/null +++ b/i18n/hi/docusaurus-plugin-content-docs/current/stacks-academy/sips.md @@ -0,0 +1,52 @@ +--- +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/IJ15791776) 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-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. From d1d7184f98994d5f9a0742f7221a9fbedb908056 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 5 Feb 2023 05:49:22 +0100 Subject: [PATCH 0781/1444] New translations hosted-nodes.md (Hindi) --- .../current/nodes-and-miners/hosted-nodes.md | 25 +++++++++++++++++++ 1 file changed, 25 insertions(+) create mode 100644 i18n/hi/docusaurus-plugin-content-docs/current/nodes-and-miners/hosted-nodes.md diff --git a/i18n/hi/docusaurus-plugin-content-docs/current/nodes-and-miners/hosted-nodes.md b/i18n/hi/docusaurus-plugin-content-docs/current/nodes-and-miners/hosted-nodes.md new file mode 100644 index 0000000000..12d86c7ee2 --- /dev/null +++ b/i18n/hi/docusaurus-plugin-content-docs/current/nodes-and-miners/hosted-nodes.md @@ -0,0 +1,25 @@ +--- +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. From 2b2deeb9cf7aae453b692ab56d05c0b991fd68b7 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Fri, 10 Feb 2023 16:00:59 +0100 Subject: [PATCH 0782/1444] Update source file crash-course.md --- docs/clarity/crash-course.md | 123 +++++++++++++++++++++++++++++++++++ 1 file changed, 123 insertions(+) create mode 100644 docs/clarity/crash-course.md diff --git a/docs/clarity/crash-course.md b/docs/clarity/crash-course.md new file mode 100644 index 0000000000..4e3b07ebba --- /dev/null +++ b/docs/clarity/crash-course.md @@ -0,0 +1,123 @@ +--- +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.md). + +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. + +```clojure +(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: + +```clojure +(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. From e77a1d881a8724d4fabcf4edce96a2f77880d1a2 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Fri, 10 Feb 2023 16:00:59 +0100 Subject: [PATCH 0783/1444] Update source file index.md --- docs/clarity/index.md | 58 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 58 insertions(+) create mode 100644 docs/clarity/index.md diff --git a/docs/clarity/index.md b/docs/clarity/index.md new file mode 100644 index 0000000000..903de93a45 --- /dev/null +++ b/docs/clarity/index.md @@ -0,0 +1,58 @@ +--- +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?2 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. If you are unsure what this means, let it not worry you for now. The serious advantage of decidability will become more apparent over time. + +### 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. From b1f11bcdf5ad25a6022765cb28e94d40e3d8b9d1 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Fri, 10 Feb 2023 16:01:00 +0100 Subject: [PATCH 0784/1444] Update source file language-functions.md --- docs/clarity/language-functions.md | 2246 ++++++++++++++++++++++++++++ 1 file changed, 2246 insertions(+) create mode 100644 docs/clarity/language-functions.md diff --git a/docs/clarity/language-functions.md b/docs/clarity/language-functions.md new file mode 100644 index 0000000000..6848e5ed1f --- /dev/null +++ b/docs/clarity/language-functions.md @@ -0,0 +1,2246 @@ +--- +title: Functions +description: See a detailed list of all functions for the Clarity language. +sidebar_position: 3 +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: + +#### 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-existent\"))))) ;; 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-existent\") ;; 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-existent\" })) ;; 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-existent\" }))) ;; 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-existent\" }))) ;; 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 \"Stacks\" '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 successfully 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_ transferred from another principal, but +rather minted. + +If a non-positive amount is provided to mint, this function returns `(err 1)`. Otherwise, on successfully 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_ transferred 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 successfully 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 successfully 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)) +``` From e3701c0f3d84fbf06d67ab63689bfc55c35118eb Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Fri, 10 Feb 2023 16:01:01 +0100 Subject: [PATCH 0785/1444] Update source file language-keywords.md --- docs/clarity/language-keywords.md | 147 ++++++++++++++++++++++++++++++ 1 file changed, 147 insertions(+) create mode 100644 docs/clarity/language-keywords.md diff --git a/docs/clarity/language-keywords.md b/docs/clarity/language-keywords.md new file mode 100644 index 0000000000..9cde839e05 --- /dev/null +++ b/docs/clarity/language-keywords.md @@ -0,0 +1,147 @@ +--- +title: Keywords +description: See a detailed list of all keywords for the Clarity language. +sidebar_position: 4 +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 +``` From eeb01074fa63abc6e666fd329f1d556d6099c79a Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Fri, 10 Feb 2023 16:01:01 +0100 Subject: [PATCH 0786/1444] Update source file language-types.md --- docs/clarity/language-types.md | 25 +++++++++++++++++++++++++ 1 file changed, 25 insertions(+) create mode 100644 docs/clarity/language-types.md diff --git a/docs/clarity/language-types.md b/docs/clarity/language-types.md new file mode 100644 index 0000000000..8c7bc0e8cd --- /dev/null +++ b/docs/clarity/language-types.md @@ -0,0 +1,25 @@ +--- +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. | From 703816cdbb19634337b27869149a72162625ba72 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Fri, 10 Feb 2023 16:01:02 +0100 Subject: [PATCH 0787/1444] Update source file bns-contract.md --- .../noteworthy-contracts/bns-contract.md | 522 ++++++++++++++++++ 1 file changed, 522 insertions(+) create mode 100644 docs/clarity/noteworthy-contracts/bns-contract.md diff --git a/docs/clarity/noteworthy-contracts/bns-contract.md b/docs/clarity/noteworthy-contracts/bns-contract.md new file mode 100644 index 0000000000..4b5df1b386 --- /dev/null +++ b/docs/clarity/noteworthy-contracts/bns-contract.md @@ -0,0 +1,522 @@ +--- +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 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` From e5efe0a13fca6fe8c2c0c9d143aacd108e743521 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Fri, 10 Feb 2023 16:01:03 +0100 Subject: [PATCH 0788/1444] Update source file stacking-contract.md --- .../noteworthy-contracts/stacking-contract.md | 352 ++++++++++++++++++ 1 file changed, 352 insertions(+) create mode 100644 docs/clarity/noteworthy-contracts/stacking-contract.md diff --git a/docs/clarity/noteworthy-contracts/stacking-contract.md b/docs/clarity/noteworthy-contracts/stacking-contract.md new file mode 100644 index 0000000000..c0027256cd --- /dev/null +++ b/docs/clarity/noteworthy-contracts/stacking-contract.md @@ -0,0 +1,352 @@ +--- +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. 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` From bbeb72c39cb38fb20a63517771a8df88f4bffeef Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Fri, 10 Feb 2023 16:01:03 +0100 Subject: [PATCH 0789/1444] Update source file xbtc.md --- docs/clarity/noteworthy-contracts/xbtc.md | 28 +++++++++++++++++++++++ 1 file changed, 28 insertions(+) create mode 100644 docs/clarity/noteworthy-contracts/xbtc.md diff --git a/docs/clarity/noteworthy-contracts/xbtc.md b/docs/clarity/noteworthy-contracts/xbtc.md new file mode 100644 index 0000000000..e535dcf260 --- /dev/null +++ b/docs/clarity/noteworthy-contracts/xbtc.md @@ -0,0 +1,28 @@ +--- +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) From 88a75372648127383b4b7420eb190523de7d666a Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Fri, 10 Feb 2023 16:01:04 +0100 Subject: [PATCH 0790/1444] Update source file sample-contracts.md --- docs/clarity/sample-contracts.md | 14 ++++++++++++++ 1 file changed, 14 insertions(+) create mode 100644 docs/clarity/sample-contracts.md diff --git a/docs/clarity/sample-contracts.md b/docs/clarity/sample-contracts.md new file mode 100644 index 0000000000..adb12a58fd --- /dev/null +++ b/docs/clarity/sample-contracts.md @@ -0,0 +1,14 @@ +--- +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) From 012078785705d3ec4c7c45f75056aebbf0e3503a Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Fri, 10 Feb 2023 16:01:04 +0100 Subject: [PATCH 0791/1444] Update source file docs.md --- docs/contribute/docs.md | 24 +++++++++++++++--------- 1 file changed, 15 insertions(+), 9 deletions(-) diff --git a/docs/contribute/docs.md b/docs/contribute/docs.md index 714193851d..1c08e25868 100644 --- a/docs/contribute/docs.md +++ b/docs/contribute/docs.md @@ -7,7 +7,7 @@ description: Learn how this site is built, and how you can contribute to it. 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). +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/). @@ -19,7 +19,7 @@ Don't want to learn it? No need to. Write [in plain text an issue on Github](htt 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 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). @@ -28,28 +28,32 @@ To add new content, they are two different ways to do it, the [easy way](#easy-w [**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. +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 yourhanges in real time. + - `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. -## Aditional information +## 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 ``` @@ -58,8 +62,8 @@ Before running this command for the first time you will need to run `npm install 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 ``` @@ -97,7 +101,7 @@ 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. +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 @@ -131,6 +135,7 @@ And execute prettier with the following command: npx prettier --write mynewfiletocheck.md ``` --> + ### 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. @@ -145,6 +150,7 @@ To write a code block, you need to wrap your code in ` ```language `, and end yo (define-public (get-counter) (ok (var-get counter))) ``` + ### Admonitions You can use the following admonitions to highlight content. @@ -211,4 +217,4 @@ Some **content** with _markdown_ `syntax`. Some **content** with _markdown_ `syntax`. -::: \ No newline at end of file +::: From f57ba6e4f0191d18daecda42d70a24ed1dc72569 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Fri, 10 Feb 2023 16:01:05 +0100 Subject: [PATCH 0792/1444] Update source file translations.md --- docs/contribute/translations.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/contribute/translations.md b/docs/contribute/translations.md index 5774859f6b..bb2e9d95e2 100644 --- a/docs/contribute/translations.md +++ b/docs/contribute/translations.md @@ -1,26 +1,26 @@ --- title: Contribute with translations -description: Want to help tranlating these docs to your local language? +description: Want to help translating 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. +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 Crodin intead. +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 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 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) From a5e4ff86c238986a013519c4016d469632cd7a1b Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Fri, 10 Feb 2023 16:01:06 +0100 Subject: [PATCH 0793/1444] Update source file creating-an-ft.md --- docs/cookbook/creating-an-ft.md | 99 +++++++++++++++++++++++++++++++++ 1 file changed, 99 insertions(+) create mode 100644 docs/cookbook/creating-an-ft.md diff --git a/docs/cookbook/creating-an-ft.md b/docs/cookbook/creating-an-ft.md new file mode 100644 index 0000000000..4e3bad99d2 --- /dev/null +++ b/docs/cookbook/creating-an-ft.md @@ -0,0 +1,99 @@ +--- +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) + ) +) +``` From 2a30141d5167b8f49c15245230494d45355fbf85 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Fri, 10 Feb 2023 16:01:07 +0100 Subject: [PATCH 0794/1444] Update source file creating-an-nft.md --- docs/cookbook/creating-an-nft.md | 87 ++++++++++++++++++++++++++++++++ 1 file changed, 87 insertions(+) create mode 100644 docs/cookbook/creating-an-nft.md diff --git a/docs/cookbook/creating-an-nft.md b/docs/cookbook/creating-an-nft.md new file mode 100644 index 0000000000..08faf9393a --- /dev/null +++ b/docs/cookbook/creating-an-nft.md @@ -0,0 +1,87 @@ +--- +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 +Code for this recipe has been pulled from [this NFT tutorial](https://blog.developerdao.com/building-an-nft-with-stacks-and-clarity) from Developer DAO. +::: + +## 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) + ) +) +``` From f502fa1d39d9a56d97adef9c11158e2a92e25cec Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Fri, 10 Feb 2023 16:01:07 +0100 Subject: [PATCH 0795/1444] Update source file index.md --- docs/cookbook/index.md | 64 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 64 insertions(+) create mode 100644 docs/cookbook/index.md diff --git a/docs/cookbook/index.md b/docs/cookbook/index.md new file mode 100644 index 0000000000..a2b0e42eea --- /dev/null +++ b/docs/cookbook/index.md @@ -0,0 +1,64 @@ +--- +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 + +Swapping between Bitcoin and Stacks addresses + +Swapping between xBTC and BTC + +Verifying a transaction on the BTC chain + +## 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 + +Airdropping an NFT to a Bitcoin address + +## Stacking and Mining + +Simple stacking pool + +Continuous stacking + +Simple mining pool + +Proof of PoX payout + +## Oracles + +Creating a simple BTC price oracle + +## Frontend + +[Post conditions with Stacks.js](./post-conditions) + +[Authentication with Stacks.js](./stacks-js-auth) + +[Sending transactions with Stacks.js](./stacks-js-sending-transactions) + +## Complete Apps + +[Sup](https://github.com/kenrogers/sup) + +[Hello Stacks](https://github.com/kenrogers/hello-stacks) From 3062945e1411635f10db90e3affe3758fcaf538b Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Fri, 10 Feb 2023 16:01:08 +0100 Subject: [PATCH 0796/1444] Update source file post-conditions.md --- docs/cookbook/post-conditions.md | 136 +++++++++++++++++++++++++++++++ 1 file changed, 136 insertions(+) create mode 100644 docs/cookbook/post-conditions.md diff --git a/docs/cookbook/post-conditions.md b/docs/cookbook/post-conditions.md new file mode 100644 index 0000000000..571fc20d48 --- /dev/null +++ b/docs/cookbook/post-conditions.md @@ -0,0 +1,136 @@ +--- +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. From 7b3aaeae6779b12cb829c69e92e2b5e8c06a95fc Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Fri, 10 Feb 2023 16:01:08 +0100 Subject: [PATCH 0797/1444] Update source file stacks-js-auth.md --- docs/cookbook/stacks-js-auth.md | 98 +++++++++++++++++++++++++++++++++ 1 file changed, 98 insertions(+) create mode 100644 docs/cookbook/stacks-js-auth.md diff --git a/docs/cookbook/stacks-js-auth.md b/docs/cookbook/stacks-js-auth.md new file mode 100644 index 0000000000..89d1f06e00 --- /dev/null +++ b/docs/cookbook/stacks-js-auth.md @@ -0,0 +1,98 @@ +--- +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 && ( + + ); +} +``` From 53e967718e339fac4d68215ea344c875b140799a Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Fri, 10 Feb 2023 16:01:09 +0100 Subject: [PATCH 0798/1444] Update source file stacks-js-sending-transactions.md --- .../stacks-js-sending-transactions.md | 55 +++++++++++++++++++ 1 file changed, 55 insertions(+) create mode 100644 docs/cookbook/stacks-js-sending-transactions.md diff --git a/docs/cookbook/stacks-js-sending-transactions.md b/docs/cookbook/stacks-js-sending-transactions.md new file mode 100644 index 0000000000..849c7d1f42 --- /dev/null +++ b/docs/cookbook/stacks-js-sending-transactions.md @@ -0,0 +1,55 @@ +--- +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. From a85b3f4860b8a8582ef7b41d52011f05405633b3 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Fri, 10 Feb 2023 16:01:10 +0100 Subject: [PATCH 0799/1444] Update source file gaia-on-ec2.md --- docs/gaia/gaia-on-ec2.md | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-) diff --git a/docs/gaia/gaia-on-ec2.md b/docs/gaia/gaia-on-ec2.md index 418dee4850..dca15e3b8d 100644 --- a/docs/gaia/gaia-on-ec2.md +++ b/docs/gaia/gaia-on-ec2.md @@ -26,9 +26,10 @@ Use a link in the table to launch the [CloudFormation](https://console.aws.amazo ### Step 2 - Setup stack using template -You need to configure the template with the appropiate values for your hub and domain it runs on. +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 ``` @@ -48,12 +49,12 @@ Specify the stack details and then click `Next`: | Field | Value | Notes | | --------------- | ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| Stack name | _a unique name in your AWS account_ | e.g.: my_gaia_hub +| 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`. | +| 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 | @@ -95,7 +96,9 @@ If you can only access SSH with the IP but not with the DNS name and you wish to 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 +![](/img/cloudformation-gaia-template1-designer.png) From 04d103e1e47ea2efdeef2bdbcc8c8cadcf6fcae7 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Fri, 10 Feb 2023 16:01:10 +0100 Subject: [PATCH 0800/1444] Update source file gaia.md --- docs/gaia/gaia.md | 12 +++++++++--- 1 file changed, 9 insertions(+), 3 deletions(-) diff --git a/docs/gaia/gaia.md b/docs/gaia/gaia.md index 8c797a20e9..ccae8da80a 100644 --- a/docs/gaia/gaia.md +++ b/docs/gaia/gaia.md @@ -1,14 +1,20 @@ --- title: Gaia description: Decentralized storage architecture for off-chain data -sidebar_position: 5 +sidebar_position: 6 tags: - gaia --- ## Introduction -Apps built with the Stacks blockchain store off-chain data using a storage system called Gaia. +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. @@ -42,7 +48,7 @@ The Stacks blockchain stores only identity data. Data created by the actions of 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) +![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. From 833299e355523fa874b2b1a26188ca064d999087 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Fri, 10 Feb 2023 16:01:11 +0100 Subject: [PATCH 0801/1444] Update source file setup-linux.md --- docs/gaia/setup-linux.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/gaia/setup-linux.md b/docs/gaia/setup-linux.md index a9ce8c06c7..b19a74a13d 100644 --- a/docs/gaia/setup-linux.md +++ b/docs/gaia/setup-linux.md @@ -1,6 +1,6 @@ --- 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. +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 @@ -19,7 +19,7 @@ This configuration will setup the following 4 docker containers: 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. +**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 @@ -48,8 +48,8 @@ chmod +x ${DESTINATION_DC}/docker-compose 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. +**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 From 3daebd27fcb6be53b22d1a84c05e784ee4d6a54d Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Fri, 10 Feb 2023 16:01:12 +0100 Subject: [PATCH 0802/1444] Update source file index.md --- docs/glossary/index.md | 294 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 294 insertions(+) create mode 100644 docs/glossary/index.md diff --git a/docs/glossary/index.md b/docs/glossary/index.md new file mode 100644 index 0000000000..b389c50dde --- /dev/null +++ b/docs/glossary/index.md @@ -0,0 +1,294 @@ +--- +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. From f645982fcf390b352d1c9427557a1bcda3cfe87f Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Fri, 10 Feb 2023 16:01:13 +0100 Subject: [PATCH 0803/1444] Update source file index.md --- docs/next-steps/index.md | 39 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 39 insertions(+) create mode 100644 docs/next-steps/index.md diff --git a/docs/next-steps/index.md b/docs/next-steps/index.md new file mode 100644 index 0000000000..00ddec9178 --- /dev/null +++ b/docs/next-steps/index.md @@ -0,0 +1,39 @@ +--- +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) From 1b8b14cc3fafb42dde7f37c700f52b8fcad6b026 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Fri, 10 Feb 2023 16:01:13 +0100 Subject: [PATCH 0804/1444] Update source file digitalocean.md --- docs/nodes-and-miners/digitalocean.md | 44 ++++++++++++++++++--------- 1 file changed, 29 insertions(+), 15 deletions(-) diff --git a/docs/nodes-and-miners/digitalocean.md b/docs/nodes-and-miners/digitalocean.md index 801de7f6f0..cf842d4762 100644 --- a/docs/nodes-and-miners/digitalocean.md +++ b/docs/nodes-and-miners/digitalocean.md @@ -1,29 +1,32 @@ --- -title: Stacks on DigitalOcean +title: Run a Node with Digital Ocean description: A guide to setup Stacks on DigitalOcean -sidebar_position: 4 +sidebar_position: 2 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). +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 plan that meets the minimum requirements) and your prefered datacenter region. +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 if your prefer. +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) @@ -48,41 +51,52 @@ Congratulations! You are now running the Stacks Blockchain. You can click on `Co ## 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). +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`. -Once the stacks blockchain starts to sync with peers, application ports will open and nginx port 80 will now start proxying requests. +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 v3.0.3 (master:cd0c8aef)", + "server_version": "stacks-blockchain-api v6.2.3 (master:77ab3ae2)", "status": "ready", "chain_tip": { - "block_height": 16220, - "block_hash": "0x3123fba9c0de6b569573494cf83c1d5d198a66bfd5f48ef97949b6bf11ba13be", - "index_block_hash": "0xeec960fbbd6186b4ccac85ce12adba72be497d881f81e077305c90955b51a6ae" + "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/README.md#quickstart). +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). -## API Creation +## 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 -curl -X POST -H 'Content-Type: application/json' \ +$ export TOKEN= +$ 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"}' \ + '{"name":"stacks-blockchain","region":"sfo2","size":"s-2vcpu-4gb","image":"stacksfoundation-stacksblockchain"}' \ "https://api.digitalocean.com/v2/droplets" ``` From 017d87be4f774f8ab4a1fa2e887f2e8d03b4bae0 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Fri, 10 Feb 2023 16:01:14 +0100 Subject: [PATCH 0805/1444] Update source file hosted-nodes.md --- docs/nodes-and-miners/hosted-nodes.md | 26 ++++++++++++++++++++++++++ 1 file changed, 26 insertions(+) create mode 100644 docs/nodes-and-miners/hosted-nodes.md diff --git a/docs/nodes-and-miners/hosted-nodes.md b/docs/nodes-and-miners/hosted-nodes.md new file mode 100644 index 0000000000..eb8c25322f --- /dev/null +++ b/docs/nodes-and-miners/hosted-nodes.md @@ -0,0 +1,26 @@ +--- +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. From 948fd6463be8e0d2071e5d8bf7e81d609d512c9e Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Fri, 10 Feb 2023 16:01:14 +0100 Subject: [PATCH 0806/1444] Update source file index.md --- docs/nodes-and-miners/index.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/nodes-and-miners/index.md b/docs/nodes-and-miners/index.md index b6cbb9754a..e5f4f2c250 100644 --- a/docs/nodes-and-miners/index.md +++ b/docs/nodes-and-miners/index.md @@ -1,11 +1,11 @@ --- title: Nodes and Miners description: Nodes and Miners -sidebar_position: 7 +sidebar_position: 5 --- -Here are all the steps to run nodes and miners, both on mainnet and testnet. +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. -## What's a Stacks node? +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. -## What's a Stacks miner? +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. From a145ee972b375922172a1d999b7904b2cfaac338 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Fri, 10 Feb 2023 16:01:15 +0100 Subject: [PATCH 0807/1444] Update source file miner-costs-and-fees.md --- docs/nodes-and-miners/miner-costs-and-fees.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/nodes-and-miners/miner-costs-and-fees.md b/docs/nodes-and-miners/miner-costs-and-fees.md index 26a5d02a63..f1838b6268 100644 --- a/docs/nodes-and-miners/miner-costs-and-fees.md +++ b/docs/nodes-and-miners/miner-costs-and-fees.md @@ -8,7 +8,7 @@ sidebar_position: 8 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 @@ -26,3 +26,5 @@ Cost estimators are **not** consensus-critical components, but rather can be use 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). From d5a52475255ebfe6ae328448a7e7095d7b1cfc80 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Fri, 10 Feb 2023 16:01:16 +0100 Subject: [PATCH 0808/1444] Update source file miner-mainnet.md --- docs/nodes-and-miners/miner-mainnet.md | 313 ++++++++++--------------- 1 file changed, 120 insertions(+), 193 deletions(-) diff --git a/docs/nodes-and-miners/miner-mainnet.md b/docs/nodes-and-miners/miner-mainnet.md index cc10d1f143..59b955a976 100644 --- a/docs/nodes-and-miners/miner-mainnet.md +++ b/docs/nodes-and-miners/miner-mainnet.md @@ -1,166 +1,105 @@ --- title: Mine mainnet Stacks tokens -description: Set up and run a miner on the Stacks 2.0 mainnet -sidebar_position: 5 +description: Set up and run a miner on Stacks Mainnet +sidebar_position: 6 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. +For more on the technical details of mining, please review the [mining guide](../stacks-academy/mining) -If you're interested in mining on the testnet, you can find instructions on how to do that [here](miner-testnet): +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 want to learn more about the technical details of mining, please review the [mining guide](../understand-stacks/mining): +If you're interested in mining on the Stacks testnet, you can find instructions on how to do that [here](miner-testnet): -## Running bitcoind locally +## Running a Bitcoin Mainnet Full Node -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) +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. -First, download the bitcoind software for your platform from https://bitcoin.org/en/download. +- [Ensure your computer meets the minimum hardware requirements before continuing.](https://bitcoin.org/en/bitcoin-core/features/requirements#system-requirements) -Next, start bitcoind with the following configuration: +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): -```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). +:::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 -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). +Next, update the bitcoin configuration: -Update the following properties: +- **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 -[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 = "" -... +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 ``` -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. +### Start Bitcoin -To run your miner, run this in the command line: +Finally, start bitcoin as follows (adjust the `conf` path to where it was created in the previous step, i.e. `$HOME/bitcoin.conf`): ```bash -stacks-node start --config=./testnet/stacks-node/conf/mainnet-miner-conf.toml +bitcoind -conf=$HOME/bitcoin.conf ``` -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 -``` +:::note +It will take a few days for the node to synchronize with Bitcoin mainnet. +::: -The above code will compile an optimized binary. To use it, run: +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 -cd ../.. -./target/release/stacks-node start --config=./mainnet-miner-conf.toml +$ bitcoin-cli \ + -rpcconnect=localhost \ + -rpcport=8332 \ + -rpcuser=btcuser \ + -rpcpassword=btcpassword \ +getblockchaininfo | jq .blocks +773281 ``` -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 +## Running a Stacks Blockchain miner -### Prerequisites +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) -Make sure are [running a node](run-a-node) and [running bitcoind locally](#running-bitcoind-locally) before starting this tutorial. +_There may be some extra requirements to building, [defined here](https://github.com/stacksfoundation/miner-docs/blob/main/prerequisites.md#install-required-packages)_ -### Generate keychain and get mainnet tokens in Windows +:::tip +It is recommened to use a persistent location for the chainstate, in the steps below we're using `/stacks-blockchain` +::: -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. +### Generate a keychain -To get a keychain, the simplest way is to use the `stacks-cli`. We'll use the `stx make-keychain` command. +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. -Generate a keychain: +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 -npm install --global @stacks/cli -stx make_keychain > cli_keychain.json -type cli_keychain.json +npx @stacks/cli make_keychain 2>/dev/null | jq -r ``` -After this runs, you'll probably see some installation logs, and at the end you should see some JSON that looks like this: +After this runs, you should see some JSON printed to the screen that looks like this: ```json { @@ -174,114 +113,107 @@ After this runs, you'll probably see some installation logs, and at the end you } ``` -:::tip -Check out the [Stacks CLI reference](https://docs.hiro.so/references/stacks-cli) for more details +:::warning +**Do not lose this information** - we'll need to use the `privateKey` and `btcAddress` fields in later steps. ::: -The above BTC address will then need to be imported into the BTC network. +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=your-user -rpcpassword=your-password importaddress +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 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 Stacks Blockchain Configuration File -Update the following properties: +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] -... -# Enter your private key here -seed = "replace-with-your-private-key" -local_peer_seed = "replace-with-your-private-key" -... +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] -... -# To mine on mainnet, you need to run bitcoind locally -# Details can be found in above section, 'Running bitcoind locally' +chain = "bitcoin" +mode = "mainnet" peer_host = "127.0.0.1" -username = "" -password = "" -... +username = "" +password = "" +rpc_port = 8332 +peer_port = 8333 +satoshis_per_byte = 100 +burn_fee_cap = 20000 ``` -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 Stacks Blockchain -### Run the miner - -To start your miner, run this in the command line: +To run your miner, run this in the command line: ```bash -stacks-node start --config=testnet/stacks-node/conf/mainnet-miner-conf.toml +stacks-node start --config=$HOME/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 +### 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 -set RUST_BACKTRACE=full; -set STACKS_LOG_DEBUG=1; -stacks-node start --config=mainnet-miner-conf.toml +STACKS_LOG_DEBUG=1 stacks-node start --config=$HOME/mainnet-miner-conf.toml ``` -## Optional: Running with Docker +--- + +## Optional: Running a Stacks Blockchain miner with Docker -Alternatively, you can run the mainnet node with Docker. +Alternatively, you can run a Stacks mainnet miner with Docker. :::caution -Ensure you have [Docker](https://docs.docker.com/get-docker/) installed on your machine. +Ensure you have [Docker](https://docs.docker.com/get-docker/) installed. ::: -### Generate keychain and get tokens +### 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 +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 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). +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 the following properties: +### Update Stacks Blockchain Docker Configuration File -```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 = "" -... -``` +Use the steps oulined above to create the [configuration file](miner-mainnet#update-the-stacks-blockchain-configuration-file) -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 +### 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 @@ -294,7 +226,8 @@ docker run -d \ --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" \ + -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 \ @@ -309,9 +242,9 @@ 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). +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 on your machine: +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) @@ -320,13 +253,7 @@ Ensure you have the following prerequisites installed on your machine: ### 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). +Use the steps [outlined above](miner-mainnet#generate-a-keychain-and-get-some-tokens) ### Install the chart and run the miner From fb9e90aab6b9552b5e379a0610ad2ff53972cc7e Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Fri, 10 Feb 2023 16:01:16 +0100 Subject: [PATCH 0809/1444] Update source file miner-testnet.md --- docs/nodes-and-miners/miner-testnet.md | 331 +++++++++++-------------- 1 file changed, 140 insertions(+), 191 deletions(-) diff --git a/docs/nodes-and-miners/miner-testnet.md b/docs/nodes-and-miners/miner-testnet.md index eaaa32d044..0a83d57a73 100644 --- a/docs/nodes-and-miners/miner-testnet.md +++ b/docs/nodes-and-miners/miner-testnet.md @@ -1,35 +1,54 @@ --- title: Mine testnet Stacks tokens -description: Set up and run a miner on the Stacks 2.0 testnet -sidebar_position: 4 +description: Set up and run a miner on Stacks Testnet +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 testnet. +For more on the technical details of mining, please review the [mining guide](../stacks-academy/mining) -If you want to learn more about the technical details of mining, please review the [mining guide](../understand-stacks/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)). -## Running bitcoind locally +If you're interested in mining on the Stacks mainnet, you can find instructions on how to do that [here](miner-mainnet): -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) +## Running a Bitcoin Testnet Full Node -First, download the bitcoind software for your platform from https://bitcoin.org/en/download. +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. -Next, start bitcoind with the following configuration: +- [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 -rpcuser=your-bitcoind-username -rpcpassword=your-bitcoind-password testnet=1 -txindex=0 -listen=1 -rpcserialversion=0 -maxorphantx=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 @@ -37,126 +56,53 @@ rpcbind=0.0.0.0:18332 rpcport=18332 ``` -Finally, start bitcoind as follows: - -```bash -bitcoind -conf=path/to/bitcoin.conf -``` +### Start Bitcoin -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: +Finally, start bitcoind as follows: ```bash -stacks-node start --config=./testnet/stacks-node/conf/testnet-miner-conf.toml +bitcoind -conf=$HOME/bitcoin.conf ``` -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 -``` +:::note +It will take a few hours for the node to synchronize with Bitcoin testnet. +::: -The above code will compile an optimized binary. To use it, run: +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 -cd ../.. -./target/release/stacks-node start --config=./testnet/conf/testnet-follower-conf.toml +$ bitcoin-cli \ + -rpcconnect=localhost \ + -rpcport=18332 \ + -rpcuser=btcuser \ + -rpcpassword=btcpass \ +getblockchaininfo | jq .blocks +2417570 ``` -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 +## Running a Stacks Blockchain miner -### Prerequisites +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) -Make sure are [running a testnet node](run-a-node) before starting this tutorial. +_There may be some extra requirements to building, [defined here](https://github.com/stacksfoundation/miner-docs/blob/main/prerequisites.md#install-required-packages)_ -### Generate keychain and get testnet tokens in Windows +:::tip +It is recommened to use a persistent location for the chainstate, in the steps below we're using `/stacks-blockchain` +::: -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. +### Generate a keychain -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. +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. -Generate a keychain: +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 -npm install --global @stacks/cli -stx make_keychain -t > cli_keychain.json -type cli_keychain.json +npx @stacks/cli make_keychain -t 2>/dev/null | jq -r ``` -After this runs, you'll probably see some installation logs, and at the end you should see some JSON that looks like this: +After this runs, you should see some JSON printed to the screen that looks like this: ```json { @@ -170,112 +116,118 @@ After this runs, you'll probably see some installation logs, and at the end you } ``` -:::tip -Check out the [Stacks CLI reference](https://docs.hiro.so/references/stacks-cli) for more details +:::warning +**Do not lose this information** - we'll need to use the `privateKey` and `btcAddress` fields in later steps. ::: -Request BTC from faucet: +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 -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. 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`. -### Update configuration file +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. -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). +Next, update the bitcoin configuration: -Update the following properties: +- **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] -... -seed = "replace-with-your-private-key" -local_peer_seed = "replace-with-your-private-key" -... +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] -... -# To mine on Testnet, you need to run bitcoind locally -# Details can be found in above section, 'Running bitcoind locally' +chain = "bitcoin" +mode = "xenon" peer_host = "127.0.0.1" -username = "" -password = "" -... +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 ``` -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 Stacks Blockchain -### Run the miner - -To start your miner, run this in the command line: +To run your miner, run this in the command line: ```bash -stacks-node start --config=testnet/stacks-node/conf/testnet-miner-conf.toml +stacks-node start --config=$HOME/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 +### 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 -set RUST_BACKTRACE=full; -set STACKS_LOG_DEBUG=1; -stacks-node start --config=testnet-miner-conf.toml +STACKS_LOG_DEBUG=1 stacks-node start --config=$HOME/testnet-miner-conf.toml ``` -## Optional: Running with Docker +--- -Alternatively, you can run the testnet node with Docker. +## Optional: Running a Stacks Blockchain miner with Docker -:::warning -Ensure you have [Docker](https://docs.docker.com/get-docker/) installed on your machine. +Alternatively, you can run a Stacks testnet miner with Docker. + +:::caution +Ensure you have [Docker](https://docs.docker.com/get-docker/) installed ::: -### Generate keychain and get testnet tokens +### Generate a Keychain and Get Some Tokens Generate a keychain: ```bash -docker run -i node:14-alpine npx @stacks/cli make_keychain -t 2>/dev/null +docker run -i node:14-alpine npx @stacks/cli make_keychain 2>/dev/null | jq -r ``` -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: +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. -```toml -[node] -... -seed = "replace-with-your-private-key" -local_peer_seed = "replace-with-your-private-key" -... +### Update Stacks Blockchain Docker Configuration File -[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. +Use the steps oulined above to create the [configuration file](miner-testnet#update-the-stacks-blockchain-configuration-file) -### Start the miner +### 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 @@ -288,7 +240,8 @@ docker run -d \ --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" \ + -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 \ @@ -301,26 +254,22 @@ You can review the node logs with this command: 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). +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 on your machine: +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 testnet tokens - -Generate a keychain: - -```bash -docker run -i node:14-alpine npx @stacks/cli make_keychain -t 2>/dev/null -``` +### Generate keychain and get some tokens -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. +Use the steps [outlined above](miner-testnet#generate-a-keychain-and-get-some-tokens) ### Install the chart and run the miner @@ -331,7 +280,7 @@ 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.node.seed="replace-with-your-privateKey-from-generate-keychain-step" \ ``` You can review the node logs with this command: From 681186e1dd03b8654c0270283139a2fc39593afa Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Fri, 10 Feb 2023 16:01:17 +0100 Subject: [PATCH 0810/1444] Update source file quicknode.md --- docs/nodes-and-miners/quicknode.md | 45 ++++++++++++++++++++++++++++++ 1 file changed, 45 insertions(+) create mode 100644 docs/nodes-and-miners/quicknode.md diff --git a/docs/nodes-and-miners/quicknode.md b/docs/nodes-and-miners/quicknode.md new file mode 100644 index 0000000000..1281964689 --- /dev/null +++ b/docs/nodes-and-miners/quicknode.md @@ -0,0 +1,45 @@ +--- +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. From 04200205ff5446dd45a2aaaeb2555ead6954f1a4 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Fri, 10 Feb 2023 16:01:17 +0100 Subject: [PATCH 0811/1444] Update source file run-a-node.md --- docs/nodes-and-miners/run-a-node.md | 338 ++++------------------------ 1 file changed, 46 insertions(+), 292 deletions(-) diff --git a/docs/nodes-and-miners/run-a-node.md b/docs/nodes-and-miners/run-a-node.md index 29812cade4..ddfe34690c 100644 --- a/docs/nodes-and-miners/run-a-node.md +++ b/docs/nodes-and-miners/run-a-node.md @@ -1,5 +1,5 @@ --- -title: Run a node +title: Run a Node with Docker description: Set up and run a Stacks node sidebar_position: 1 tags: @@ -8,350 +8,104 @@ tags: ## Stacks Blockchain with Docker -Run your own Stacks Blockchain node easily with just few commands. +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) -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](./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) -## **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: +## **Requirements:** -```bash -./manage.sh -n -a start -f proxy -``` +The **minimum viable requirements** are listed below. -- With optional bitcoin node: +While you _can_ run a node using these specs, it's _recommended_ to assign more than the minimum for better performance. -```bash -./manage.sh -n -a start -f bitcoin -``` +- ⚠️ [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_ ) -5. **Stop the Services** +:::caution MacOS with an ARM processor is NOT recommended -```bash -./manage.sh -n -a stop -``` - -6. **Retrieve Service Logs** - -```bash -./manage.sh -n -a logs -``` +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. +::: -- Export docker log files to `./exported-logs`: +## **Quickstart** -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. +The `` placeholder used below can be replaced with one of: -```bash -./manage.sh -n -a logs export -``` +- mainnet +- testnet +- mocknet -7. **Restart all services** +1. **Clone the stacks-blockchain-docker repository locally** ```bash -./manage.sh -n -a restart +git clone https://github.com/stacks-network/stacks-blockchain-docker && cd stacks-blockchain-docker ``` -- With optional proxy: +2. **Start the Services** ```bash -./manage.sh -n -a restart -f proxy +./manage.sh -n -a start ``` -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. +:::note With an optional HTTP proxy on port 80: ```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. - +./manage.sh -n -a start -f proxy ``` -9. **Download BNS data to** `./persistent-data/bns-data` - -```bash -./manage.sh bns -``` +::: -10. **Export stacks-blockchain-api events** (_Not applicable for mocknet_) +## **Accessing the services** -```bash -./manage.sh -n -a export -# check logs for completion -./manage.sh -n -a restart -``` +:::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. -11. **Replay stacks-blockchain-api events** (_Not applicable for mocknet_) +Follow the logs to track the sync progress: ```bash -./manage.sh -n -a import -# check logs for completion -./manage.sh -n -a restart +./manage.sh -n -a logs ``` -## **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` +- Ports `20443-20444` are exposed on `localhost` ```bash -curl -sL localhost:20443/v2/info | jq +curl -sL localhost:20443/v2/info | jq -r ``` **stacks-blockchain-api**: -- Port `3999` are exposed to `localhost` +- Port `3999` is exposed on `localhost` ```bash -curl -sL localhost:3999/v2/info | jq +curl -sL localhost:3999 | jq -r ``` **proxy**: -- Port `80` is exposed to `localhost` +- Port `80` is exposed on `localhost` ```bash -curl -sL localhost/v2/info | jq -curl -sL localhost/ | jq +curl -sL localhost/v2/info | jq -r +curl -sL localhost | jq -r ``` --- ## 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 +:::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): ::: -- [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 +--- From 067028b2b27c084865bb6e090013b43ca3ff987d Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Fri, 10 Feb 2023 16:01:18 +0100 Subject: [PATCH 0812/1444] Update source file stacks-node-configuration.md --- .../stacks-node-configuration.md | 168 +++++++++++------- 1 file changed, 108 insertions(+), 60 deletions(-) diff --git a/docs/nodes-and-miners/stacks-node-configuration.md b/docs/nodes-and-miners/stacks-node-configuration.md index 8603ae2506..daa1906268 100644 --- a/docs/nodes-and-miners/stacks-node-configuration.md +++ b/docs/nodes-and-miners/stacks-node-configuration.md @@ -1,7 +1,7 @@ --- title: Stacks Node Configuration description: Configuration parameters and options for the stacks-node binary -sidebar_position: 6 +sidebar_position: 4 --- ## Usage @@ -10,99 +10,147 @@ sidebar_position: 6 stacks-node sub-command [--subcommand-option ] ``` -## Subcommands +### 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 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 -### mocknet +## Configuration File Options -Start a node based on a fast local setup emulating a burnchain. Ideal for smart contract development. +The Stacks Blockchain configuration file has multiple sections under which an option may be placed. -Example: +- [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) -```bash -stacks-node mocknet -``` +For reference, several configuration file examples are [available here](https://github.com/stacks-network/stacks-blockchain/tree/master/testnet/stacks-node/conf) -### krypton +- [Example mainnet follower configuration](./stacks-node-configuration#example-mainnet-follower-configuration) -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). +### node -Example: +Contains various configuration options for the stacks-node binary. -```bash -stacks-node krypton -``` - -### testnet - -Start a node that will join and stream blocks from the public testnet. +| 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. | -Example: +### events_observer -```bash -stacks-node testnet -``` - -### mainnet +:::info +This section is _optional_ and not required -Start a node that joins and streams blocks from the public mainnet. +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. -Example: +| 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. | | -```bash -stacks-node mainnet -``` +### connection_options -### start +:::info +This section is _optional_ and not required. -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. +However, if this section is added, **all** fields are required +::: -#### Arguments +Specifies configuration options for others connecting to the stacks node. -**--config**: relative or absolute path to the TOML config file. Required. +| 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 | -Example: +### burnchain -```bash -stacks-node start --config=/path/to/config.toml -``` +This section contains configuration options pertaining to the blockchain the stacks-node binds to on the backend for proof-of-transfer (BTC). -See [Configuration File Options](#configuration-file-options) for more information. +| 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` | -#### version +#### Mining -Displays information about the current version and the release cycle. +| 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`. | -Example: +### ustx_balance -```bash -stacks-node version -``` +- `mocknet`/`testnet` only -#### help +This section contains configuration options allocating microSTX per address in the genesis block -Displays a help message. +This section can repeat multiple times, but each section can only define a single address. -Example: +:::info +This section is only required for the `testnet` and `mocknet` networks. -```bash -stacks-node help -``` +However, if this section is added, **all** fields are required +::: -## Configuration File Options +| 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 | -The TOML configuration file has multiple sections under which an option may be placed. +## Example Mainnet Follower Configuration -To see a list of example configurations, [please see this page](https://github.com/stacks-network/stacks-blockchain/tree/master/testnet/stacks-node/conf). +```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" -### Section: node +[burnchain] +chain = "bitcoin" +mode = "mainnet" +peer_host = "localhost" +username = "user" +password = "pass" +rpc_port = 8332 +peer_port = 8333 -Contains various configuration options pertaining to the stacks-node. +[[events_observer]] +endpoint = "localhost:3700" +retry_count = 255 +events_keys = ["*"] +``` -Example: + From c6329647760b96fcd6a03acb053298b163efcc72 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Fri, 10 Feb 2023 16:01:18 +0100 Subject: [PATCH 0813/1444] Update source file verify-miner.md --- docs/nodes-and-miners/verify-miner.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/nodes-and-miners/verify-miner.md b/docs/nodes-and-miners/verify-miner.md index 094e3f03a1..18e8dd3a48 100644 --- a/docs/nodes-and-miners/verify-miner.md +++ b/docs/nodes-and-miners/verify-miner.md @@ -7,7 +7,7 @@ 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 +$ 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 -``` \ No newline at end of file +``` From 85b041c2378a0e103e492284488f8cd91dea923f Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Fri, 10 Feb 2023 16:01:19 +0100 Subject: [PATCH 0814/1444] Update source file defi.md --- docs/services-using-stacks/defi.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/services-using-stacks/defi.md b/docs/services-using-stacks/defi.md index a5471c0695..a90aad85fa 100644 --- a/docs/services-using-stacks/defi.md +++ b/docs/services-using-stacks/defi.md @@ -28,7 +28,7 @@ Please edit this page to add any relevant new site that we are missing. ## Lnswap -[LNSWAP](https://www.lnswap.org). Non custiodial crypto currency exchange +[LNSWAP](https://www.lnswap.org). Non-custodial crypto currency exchange ![](/img/sh_lnswap.png) @@ -43,4 +43,3 @@ Please edit this page to add any relevant new site that we are missing. [Stackswap](https://app.stackswap.org/v2) ![](/img/sh_stackswap.png) - From 7a0371db37ec476c4e102b677f09c64ccec92755 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Fri, 10 Feb 2023 16:01:20 +0100 Subject: [PATCH 0815/1444] Update source file more.md --- docs/services-using-stacks/more.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/services-using-stacks/more.md b/docs/services-using-stacks/more.md index df0b3e2254..1e14b9a5a5 100644 --- a/docs/services-using-stacks/more.md +++ b/docs/services-using-stacks/more.md @@ -18,6 +18,6 @@ Please edit this page to add any relevant new site that we are missing. ## Sigle -[Sigle](https://www.sigle.io/) is a decentralised and open source web 3 writing platform. +[Sigle](https://www.sigle.io/) is a decentralized and open source web 3 writing platform. -![](/img/sh_sigle.png) \ No newline at end of file +![](/img/sh_sigle.png) From 6d09445896db08d55ee554cfea242ae7027870d8 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Fri, 10 Feb 2023 16:01:20 +0100 Subject: [PATCH 0816/1444] Update source file nft.md --- docs/services-using-stacks/nft.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/services-using-stacks/nft.md b/docs/services-using-stacks/nft.md index abb770663c..d582604854 100644 --- a/docs/services-using-stacks/nft.md +++ b/docs/services-using-stacks/nft.md @@ -15,6 +15,7 @@ Please edit this page to add any relevant new site that we are missing. ![website-screenshot](/img/sh_nft_byzantion.png) ### [Gamma](https://gamma.io/) + ![website-screenshot](/img/sh_nft_gamma.png) ### [Megapont](https://www.megapont.com/) @@ -35,4 +36,4 @@ Please edit this page to add any relevant new site that we are missing. ### [Superfandom](https://superfandom.io/) -![website-screenshot](/img/sh_superfandom.png) \ No newline at end of file +![website-screenshot](/img/sh_superfandom.png) From 64da0bb98e9e51db6880671337865188b5780e29 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Fri, 10 Feb 2023 16:01:21 +0100 Subject: [PATCH 0817/1444] Update source file stacks-info-sites.md --- docs/services-using-stacks/stacks-info-sites.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/services-using-stacks/stacks-info-sites.md b/docs/services-using-stacks/stacks-info-sites.md index 35ced8dac6..54f6823e33 100644 --- a/docs/services-using-stacks/stacks-info-sites.md +++ b/docs/services-using-stacks/stacks-info-sites.md @@ -30,7 +30,7 @@ Please edit this page to add any relevant new site that we are missing. ![website-screenshot](/img/sh_stxstats.png) -### [Novuminsights](https://stacks.novuminsights.com/health) +### [Novum Insights](https://stacks.novuminsights.com/health) ![website-screenshot](/img/sh_novuminsights.png) From 19a8d64dd53bf7a547a9f4d80e9a5a2e7b8a3cb5 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Fri, 10 Feb 2023 16:01:22 +0100 Subject: [PATCH 0818/1444] Update source file wallets.md --- docs/services-using-stacks/wallets.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/services-using-stacks/wallets.md b/docs/services-using-stacks/wallets.md index e5ea6c5b45..2d3fcc85f2 100644 --- a/docs/services-using-stacks/wallets.md +++ b/docs/services-using-stacks/wallets.md @@ -15,6 +15,7 @@ Please edit this page to add any relevant new site that we are missing. [Blockchain.com](https://www.blockchain.com/wallet) ![](/img/sh_blockchain.png) + ## Boom [Boom](https://boom.money) @@ -26,6 +27,7 @@ Please edit this page to add any relevant new site that we are missing. [D'CENT](https://dcentwallet.com) ![](/img/sh_dcent.png) + ## Hiro Wallet [Hiro Wallet](https://www.hiro.so/wallet) @@ -48,4 +50,4 @@ Please edit this page to add any relevant new site that we are missing. [Wise](https://wiseapp.id) -![](/img/sh_wiseapp.png) \ No newline at end of file +![](/img/sh_wiseapp.png) From f967d8ee984b5c198c3af9e6437d9a7a4db3ea4b Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Fri, 10 Feb 2023 16:01:22 +0100 Subject: [PATCH 0819/1444] Update source file accounts.md --- docs/stacks-academy/accounts.md | 225 ++++++++++++++++++++++++++++++++ 1 file changed, 225 insertions(+) create mode 100644 docs/stacks-academy/accounts.md diff --git a/docs/stacks-academy/accounts.md b/docs/stacks-academy/accounts.md new file mode 100644 index 0000000000..f5b6ec1a26 --- /dev/null +++ b/docs/stacks-academy/accounts.md @@ -0,0 +1,225 @@ +--- +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" + } + } + ] +} +``` From 6c27210ed963494c1f4e9522965561dc1da7a245 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Fri, 10 Feb 2023 16:01:22 +0100 Subject: [PATCH 0820/1444] Update source file authentication.md --- docs/stacks-academy/authentication.md | 74 +++++++++++++++++++++++++++ 1 file changed, 74 insertions(+) create mode 100644 docs/stacks-academy/authentication.md diff --git a/docs/stacks-academy/authentication.md b/docs/stacks-academy/authentication.md new file mode 100644 index 0000000000..6768e8ba8b --- /dev/null +++ b/docs/stacks-academy/authentication.md @@ -0,0 +1,74 @@ +--- +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 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. From fba64932b9e3bf969abed58180ba5bd2736efcd7 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Fri, 10 Feb 2023 16:01:23 +0100 Subject: [PATCH 0821/1444] Update source file bns.md --- docs/stacks-academy/bns.md | 405 +++++++++++++++++++++++++++++++++++++ 1 file changed, 405 insertions(+) create mode 100644 docs/stacks-academy/bns.md diff --git a/docs/stacks-academy/bns.md b/docs/stacks-academy/bns.md new file mode 100644 index 0000000000..f0605d1841 --- /dev/null +++ b/docs/stacks-academy/bns.md @@ -0,0 +1,405 @@ +--- +title: Blockchain Naming System +description: Binds Stacks usernames to off-chain state +sidebar_position: 8 +--- + +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 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). From c00508b3aac77c007a440a109b8f19598e04f015 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Fri, 10 Feb 2023 16:01:24 +0100 Subject: [PATCH 0822/1444] Update source file btc-connection.md --- docs/stacks-academy/btc-connection.md | 195 ++++++++++++++++++++++++++ 1 file changed, 195 insertions(+) create mode 100644 docs/stacks-academy/btc-connection.md diff --git a/docs/stacks-academy/btc-connection.md b/docs/stacks-academy/btc-connection.md new file mode 100644 index 0000000000..5f7e7f32bb --- /dev/null +++ b/docs/stacks-academy/btc-connection.md @@ -0,0 +1,195 @@ +--- +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. + +## Stacks Among Other Bitcoin Layers + +In the [last section](./what-is-stacks.md) we covered what Stacks actually is and what problem it is solving, but this is not a new problem. The Bitcoin write problem has been a bit of a holy grail problem in the crypto world for a while now. + +Bitcoin is the OG cryptocurrency and has the largest market cap, but it also some of the least functionality, which means if we want to make it a productive asset and use it to build a decentralized economy, we need to take a layered approach and let Bitcoin do what it does best, while creating additional layers on top of it to add functionality. + +So how does Stacks compare to some of the other approaches to layering on top of Bitcoin? + +### 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. + +## 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. + +But because it has its own execution environment and smart contract state to maintain, it needs a token to incentivize maintenance of the network. + +But it goes further than that. It is possible to build a system like this without a token using something like merge-mining or a sidechain, but then we lose out on the additional benefit of having the chain state's safety underpinned by its entire token economy's value. + +In the case of Stacks, the safety and liveness of the chain are underpinned by this value, and the stacking mechanism incentivizes network members to increase this value. + +From Jude Nelson, Stacks core developer: + +"How hard is it to cause a safety failure (i.e. a double-spend via a reorg) on just the canonical Stacks chain fork? Anyone can become a miner by spending BTC, so without loss of generality, reverting the last block on the canonical chain is at least as hard in expectation as spending more BTC than the rest of the miners combined for that block. Because each Bitcoin block selects at most one Stacks block, the act of reorging the canonical Stacks chain back N blocks is the act of winning at least N + 1 blocks built off of a common ancestor that is N blocks deep. This is a lower bound on the number of Bitcoin blocks mined during which a reorg needs to take place — in practice, honest miners will keep working on the canonical chain, and will win some Stacks blocks of their own, which in turn increases the number of Stacks blocks the reorging miners must win. + +How costly is it to carry out a reorg of N blocks? It’s a function of how valuable STX is relative to BTC — the more valuable STX are, the more BTC honest miners are committing to mining (this has borne out in practice), and thus the more BTC a reorging miner must commit. Therefore, the cost of a reorg is a function of the value of STX. + +This is similar to the economic security of a PoW blockchain. Like in PoW, each fork of the Stacks chain has its own independent “security budget” — an attacker must out-spend the security budget to carry out a reorg, and the security budget is a function of the block rewards. In PoX, the only difference is that the miners spend another blockchain’s tokens (BTC in Stacks’ case) instead of energy. Therefore, Stacks can’t be a sidechain, a drivechain, or a merge-mined chain, because none of these other systems’ security budgets are a function of their tokens’ worth. Sidechains, drivechains, and merged-mined chains all rely on external miners for their safety, since their safety is guaranteed in part by external miners validating their blocks. The onus on these systems is to get external miners to care enough to do so, and in the case of sidechains, drivechains, and blind merged-mined chains, there is an additional onus to encourage their nodes to mine blocks at all (since there is no on-chain reward for them to earn by doing so). By contrast, disinterested Bitcoin miners neither assist nor prevent a reorg in PoX — they only record the history of all Stacks forks. + +PoX offers two additional, unique security properties on top of PoW. First, no matter how much BTC a reorging miner can commit, the act of executing a reorg is going to be time-consuming. Unless the attacker can attack the Bitcoin chain itself by quickly producing a better Bitcoin fork, a reorging miner must sustain the attack for at least N + 1 Bitcoin blocks. This gives honest miners and users ample time to notice and react to the reorg attempt. + +Second, the history of block production in all Stacks forks is embedded within Bitcoin. This allows the system to leverage Bitcoin’s security budget in order to ensure that all forks are public. This is because the act of producing a hidden Stacks fork, where the fork’s block hashes are not known to the honest miners, is the act of producing a hidden canonical Bitcoin fork. Therefore, the act of producing a hidden Stacks fork is at least as hard as reorging the Bitcoin chain. A PoX chain leverages this property not to prevent reorgs, but to make reorgs unprofitable. + +By anchoring blocks to an existing blockchain, a PoX chain forces reorgs to happen out in the open, thereby giving advance warning to all honest network participants when they happen. Honest miners, users, and exchanges will see the PoX transactions for reorg attempts on the existing blockchain, and adapt their behaviors accordingly: honest miners will increase their commitments, and users and exchanges will require more confirmations for transactions. This makes the act of carrying out a reorg while also making a profit much more challenging, since malicious reorgs — like selfish mining and double-spending — rely on secrecy to work effectively. Specific to Stacks, miners are additionally required to mine for a “warm-up” period of two blocks, during which they must spend BTC at their target commit levels but will not win any Stacks blocks. So, a high-budget reorg attempt will not only be costly, but will also alert the rest of the network before the damage is done." + +- [What Kind of Blockchain is Stacks?](https://stacks.org/stacks-blockchain) + +## 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) From 3288b665002ac95bfc36ac72c142793c48c4bacf Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Fri, 10 Feb 2023 16:01:24 +0100 Subject: [PATCH 0823/1444] Update source file index.md --- docs/stacks-academy/index.md | 10 ++++++++++ 1 file changed, 10 insertions(+) create mode 100644 docs/stacks-academy/index.md diff --git a/docs/stacks-academy/index.md b/docs/stacks-academy/index.md new file mode 100644 index 0000000000..5e8c943eda --- /dev/null +++ b/docs/stacks-academy/index.md @@ -0,0 +1,10 @@ +--- +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. From 0911c35f9d66d2067906aded0374558880ef1aee Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Fri, 10 Feb 2023 16:01:25 +0100 Subject: [PATCH 0824/1444] Update source file microblocks.md --- docs/stacks-academy/microblocks.md | 145 +++++++++++++++++++++++++++++ 1 file changed, 145 insertions(+) create mode 100644 docs/stacks-academy/microblocks.md diff --git a/docs/stacks-academy/microblocks.md b/docs/stacks-academy/microblocks.md new file mode 100644 index 0000000000..ff1b38a4b2 --- /dev/null +++ b/docs/stacks-academy/microblocks.md @@ -0,0 +1,145 @@ +--- +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 From 59751ec8cd9dc2f7bfa808751cb7e8424b99bbb7 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Fri, 10 Feb 2023 16:01:25 +0100 Subject: [PATCH 0825/1444] Update source file mining.md --- docs/stacks-academy/mining.md | 87 +++++++++++++++++++++++++++++++++++ 1 file changed, 87 insertions(+) create mode 100644 docs/stacks-academy/mining.md diff --git a/docs/stacks-academy/mining.md b/docs/stacks-academy/mining.md new file mode 100644 index 0000000000..beec56e58b --- /dev/null +++ b/docs/stacks-academy/mining.md @@ -0,0 +1,87 @@ +--- +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 From 5ac2c73387118cce64bc4bb70f7be815a45707fd Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Fri, 10 Feb 2023 16:01:26 +0100 Subject: [PATCH 0826/1444] Update source file network.md --- docs/stacks-academy/network.md | 156 +++++++++++++++++++++++++++++++++ 1 file changed, 156 insertions(+) create mode 100644 docs/stacks-academy/network.md diff --git a/docs/stacks-academy/network.md b/docs/stacks-academy/network.md new file mode 100644 index 0000000000..959476e709 --- /dev/null +++ b/docs/stacks-academy/network.md @@ -0,0 +1,156 @@ +--- +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 +} +``` From 4464be374f10690d93bfb386f977af22b6f3fee0 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Fri, 10 Feb 2023 16:01:26 +0100 Subject: [PATCH 0827/1444] Update source file post-conditions.md --- docs/stacks-academy/post-conditions.md | 39 ++++++++++++++++++++++++++ 1 file changed, 39 insertions(+) create mode 100644 docs/stacks-academy/post-conditions.md diff --git a/docs/stacks-academy/post-conditions.md b/docs/stacks-academy/post-conditions.md new file mode 100644 index 0000000000..bb0727194f --- /dev/null +++ b/docs/stacks-academy/post-conditions.md @@ -0,0 +1,39 @@ +--- +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). From cd152bc194bed59460961af89feb99f119c5918d Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Fri, 10 Feb 2023 16:01:27 +0100 Subject: [PATCH 0828/1444] Update source file proof-of-transfer.md --- docs/stacks-academy/proof-of-transfer.md | 83 ++++++++++++++++++++++++ 1 file changed, 83 insertions(+) create mode 100644 docs/stacks-academy/proof-of-transfer.md diff --git a/docs/stacks-academy/proof-of-transfer.md b/docs/stacks-academy/proof-of-transfer.md new file mode 100644 index 0000000000..50f4b739d6 --- /dev/null +++ b/docs/stacks-academy/proof-of-transfer.md @@ -0,0 +1,83 @@ +--- +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. From 7d45dc443ee3fb01d26117fdce93c6e478e85a08 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Fri, 10 Feb 2023 16:01:27 +0100 Subject: [PATCH 0829/1444] Update source file sips.md --- docs/stacks-academy/sips.md | 56 +++++++++++++++++++++++++++++++++++++ 1 file changed, 56 insertions(+) create mode 100644 docs/stacks-academy/sips.md diff --git a/docs/stacks-academy/sips.md b/docs/stacks-academy/sips.md new file mode 100644 index 0000000000..1397b6a65f --- /dev/null +++ b/docs/stacks-academy/sips.md @@ -0,0 +1,56 @@ +--- +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/IJ15791776) 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-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. From 50c08329383ac12faaf561a71ce4d848954e6b37 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Fri, 10 Feb 2023 16:01:28 +0100 Subject: [PATCH 0830/1444] Update source file stacking.md --- docs/stacks-academy/stacking.md | 158 ++++++++++++++++++++++++++++++++ 1 file changed, 158 insertions(+) create mode 100644 docs/stacks-academy/stacking.md diff --git a/docs/stacks-academy/stacking.md b/docs/stacks-academy/stacking.md new file mode 100644 index 0000000000..60531dfced --- /dev/null +++ b/docs/stacks-academy/stacking.md @@ -0,0 +1,158 @@ +--- +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. 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. + +![](/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 +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 (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 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) From a7af8a9e6d66ef25440316001d3f1e7f2859a8e9 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Fri, 10 Feb 2023 16:01:28 +0100 Subject: [PATCH 0831/1444] Update source file stacks-blockchain-api.md --- docs/stacks-academy/stacks-blockchain-api.md | 47 ++++++++++++++++++++ 1 file changed, 47 insertions(+) create mode 100644 docs/stacks-academy/stacks-blockchain-api.md diff --git a/docs/stacks-academy/stacks-blockchain-api.md b/docs/stacks-academy/stacks-blockchain-api.md new file mode 100644 index 0000000000..4197ac6588 --- /dev/null +++ b/docs/stacks-academy/stacks-blockchain-api.md @@ -0,0 +1,47 @@ +--- +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`. +::: From 10d79dfa6cd05cd0ecf202742c516e6ace9966b5 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Fri, 10 Feb 2023 16:01:29 +0100 Subject: [PATCH 0832/1444] Update source file technical-specs.md --- docs/stacks-academy/technical-specs.md | 79 ++++++++++++++++++++++++++ 1 file changed, 79 insertions(+) create mode 100644 docs/stacks-academy/technical-specs.md diff --git a/docs/stacks-academy/technical-specs.md b/docs/stacks-academy/technical-specs.md new file mode 100644 index 0000000000..695f849e1a --- /dev/null +++ b/docs/stacks-academy/technical-specs.md @@ -0,0 +1,79 @@ +--- +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). +- 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 whitepaper v2](https://www.youtube.com/watch?v=Wd-Bfe8Sn-Y). From 851a10d978e9ff73e6c8d751a220472cf179013c Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Fri, 10 Feb 2023 16:01:30 +0100 Subject: [PATCH 0833/1444] Update source file testnet.md --- docs/stacks-academy/testnet.md | 35 ++++++++++++++++++++++++++++++++++ 1 file changed, 35 insertions(+) create mode 100644 docs/stacks-academy/testnet.md diff --git a/docs/stacks-academy/testnet.md b/docs/stacks-academy/testnet.md new file mode 100644 index 0000000000..f8b9f03df2 --- /dev/null +++ b/docs/stacks-academy/testnet.md @@ -0,0 +1,35 @@ +--- +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. + +### 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) From edd64381fec9a8d9c307637cf9df508b3b9d9b34 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Fri, 10 Feb 2023 16:01:30 +0100 Subject: [PATCH 0834/1444] Update source file transactions.md --- docs/stacks-academy/transactions.md | 44 +++++++++++++++++++++++++++++ 1 file changed, 44 insertions(+) create mode 100644 docs/stacks-academy/transactions.md diff --git a/docs/stacks-academy/transactions.md b/docs/stacks-academy/transactions.md new file mode 100644 index 0000000000..0cdc4d5deb --- /dev/null +++ b/docs/stacks-academy/transactions.md @@ -0,0 +1,44 @@ +--- +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). +::: From cd4cb2780d3a18fbadb9d4920a4a23ad6c343b46 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Fri, 10 Feb 2023 16:01:31 +0100 Subject: [PATCH 0835/1444] Update source file what-is-stacks.md --- docs/stacks-academy/what-is-stacks.md | 104 ++++++++++++++++++++++++++ 1 file changed, 104 insertions(+) create mode 100644 docs/stacks-academy/what-is-stacks.md diff --git a/docs/stacks-academy/what-is-stacks.md b/docs/stacks-academy/what-is-stacks.md new file mode 100644 index 0000000000..0e3210b364 --- /dev/null +++ b/docs/stacks-academy/what-is-stacks.md @@ -0,0 +1,104 @@ +--- +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. + +There's a lot of jargon, possible assumptions, controversy, and cool technology wrapped up in those statements. So let's get started by getting a 30,000 foot view of what exactly Stacks is. + +## Stacks Explained in (Slightly Less Than) 10 Minutes + +
+ +
+ +## 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, Stacks takes a different approach. + +## 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). + +By taking this 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 with some unique properties, like having its own token, that allow it to maintain a historical ledger of all of its transactions and operate with its own security budget. + +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_. + +Nope. 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. From 27cd6ea3b360b89d27aeb34c6b7534d0908a3b64 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Fri, 10 Feb 2023 16:01:31 +0100 Subject: [PATCH 0836/1444] Update source file whitepapers.md --- docs/stacks-academy/whitepapers.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) create mode 100644 docs/stacks-academy/whitepapers.md diff --git a/docs/stacks-academy/whitepapers.md b/docs/stacks-academy/whitepapers.md new file mode 100644 index 0000000000..0e564fbf44 --- /dev/null +++ b/docs/stacks-academy/whitepapers.md @@ -0,0 +1,12 @@ +--- +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) From ce08812d01c22b6ab0371ad0d6c5b648add19dea Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Fri, 10 Feb 2023 16:01:32 +0100 Subject: [PATCH 0837/1444] Update source file community-tutorials.md --- docs/tutorials/community-tutorials.md | 24 ++++++++++++++++++++++++ 1 file changed, 24 insertions(+) create mode 100644 docs/tutorials/community-tutorials.md diff --git a/docs/tutorials/community-tutorials.md b/docs/tutorials/community-tutorials.md new file mode 100644 index 0000000000..a4f3d970ca --- /dev/null +++ b/docs/tutorials/community-tutorials.md @@ -0,0 +1,24 @@ +--- +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/) From 18b33eaa647f73914c6b7945d2c7a54c420e3b1d Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Fri, 10 Feb 2023 16:01:32 +0100 Subject: [PATCH 0838/1444] Update source file hello-stacks.md --- docs/tutorials/hello-stacks.md | 759 +++++++++++++++++++++++++++++++++ 1 file changed, 759 insertions(+) create mode 100644 docs/tutorials/hello-stacks.md diff --git a/docs/tutorials/hello-stacks.md b/docs/tutorials/hello-stacks.md new file mode 100644 index 0000000000..a0a442d135 --- /dev/null +++ b/docs/tutorials/hello-stacks.md @@ -0,0 +1,759 @@ +--- +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. From 6ab53599e5e6fc8118928f2ca4b617890332889d Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Fri, 10 Feb 2023 16:01:33 +0100 Subject: [PATCH 0839/1444] Update source file index.md --- docs/tutorials/index.md | 11 +++++++++++ 1 file changed, 11 insertions(+) create mode 100644 docs/tutorials/index.md diff --git a/docs/tutorials/index.md b/docs/tutorials/index.md new file mode 100644 index 0000000000..1d544c7bc1 --- /dev/null +++ b/docs/tutorials/index.md @@ -0,0 +1,11 @@ +--- +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. From 31160fc48857d6fe2885c1bd0eed718d0f7c605a Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Fri, 10 Feb 2023 16:01:34 +0100 Subject: [PATCH 0840/1444] Update source file satoshis-ridge.md --- docs/tutorials/satoshis-ridge.md | 75 ++++++++++++++++++++++++++++++++ 1 file changed, 75 insertions(+) create mode 100644 docs/tutorials/satoshis-ridge.md diff --git a/docs/tutorials/satoshis-ridge.md b/docs/tutorials/satoshis-ridge.md new file mode 100644 index 0000000000..596339ae74 --- /dev/null +++ b/docs/tutorials/satoshis-ridge.md @@ -0,0 +1,75 @@ +--- +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 arguable one of its strengths. + +Instead, we need to create separate layers that add additional functionality without modify 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. From 9c6ee7dc9d9ad57b5058a1267a0c3a55f776f18c Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Fri, 10 Feb 2023 16:01:35 +0100 Subject: [PATCH 0841/1444] Update source file _category_.json --- docs/clarity/noteworthy-contracts/_category_.json | 8 ++++++++ 1 file changed, 8 insertions(+) create mode 100644 docs/clarity/noteworthy-contracts/_category_.json diff --git a/docs/clarity/noteworthy-contracts/_category_.json b/docs/clarity/noteworthy-contracts/_category_.json new file mode 100644 index 0000000000..77867c9414 --- /dev/null +++ b/docs/clarity/noteworthy-contracts/_category_.json @@ -0,0 +1,8 @@ +{ + "label": "Noteworthy Contracts", + "position": 4, + "link": { + "type": "generated-index", + "description": "Specific deployed Clarity Contracts worth mentioning." + } + } \ No newline at end of file From 377df721677d25221b4195ecc864994ebd8ab7fa Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Fri, 10 Feb 2023 16:01:49 +0100 Subject: [PATCH 0842/1444] New translations bns-contract.md (French) --- .../current/clarity/noteworthy-contracts/bns-contract.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/bns-contract.md b/i18n/fr/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/bns-contract.md index a7770b7d24..9e92bd758a 100644 --- a/i18n/fr/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/bns-contract.md +++ b/i18n/fr/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/bns-contract.md @@ -1,13 +1,13 @@ --- title: BNS Contract -description: The Blockchain Naming System. +description: The Bitcoin Naming System. --- ![](/img/satoshi-btc.png) ## Introduction -The Blockchain Naming System (BNS) is implemented as a smart contract using Clarity. +The Bitcoin 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: From c75a7e1e6fcb1738a13401ba97e18fc9d070cd3a Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Fri, 10 Feb 2023 16:01:50 +0100 Subject: [PATCH 0843/1444] New translations bns-contract.md (Spanish) --- .../current/clarity/noteworthy-contracts/bns-contract.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/i18n/es/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/bns-contract.md b/i18n/es/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/bns-contract.md index e7657922ca..cb13d48016 100644 --- a/i18n/es/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/bns-contract.md +++ b/i18n/es/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/bns-contract.md @@ -1,13 +1,13 @@ --- title: BNS Contract -description: The Blockchain Naming System. +description: The Bitcoin Naming System. --- ![](/img/satoshi-btc.png) ## Introducción -The Blockchain Naming System (BNS) is implemented as a smart contract using Clarity. +The Bitcoin 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: From 7af25f872edf90f2e1a9769fd0b116e3a4706c89 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Fri, 10 Feb 2023 16:01:51 +0100 Subject: [PATCH 0844/1444] New translations bns-contract.md (German) --- .../current/clarity/noteworthy-contracts/bns-contract.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/i18n/de/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/bns-contract.md b/i18n/de/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/bns-contract.md index a7770b7d24..9e92bd758a 100644 --- a/i18n/de/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/bns-contract.md +++ b/i18n/de/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/bns-contract.md @@ -1,13 +1,13 @@ --- title: BNS Contract -description: The Blockchain Naming System. +description: The Bitcoin Naming System. --- ![](/img/satoshi-btc.png) ## Introduction -The Blockchain Naming System (BNS) is implemented as a smart contract using Clarity. +The Bitcoin 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: From 15f1e3e5f6cf401d47ef040739f0a1c1b3810d73 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Fri, 10 Feb 2023 16:01:53 +0100 Subject: [PATCH 0845/1444] New translations bns-contract.md (Japanese) --- .../current/clarity/noteworthy-contracts/bns-contract.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/bns-contract.md b/i18n/ja/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/bns-contract.md index a7770b7d24..9e92bd758a 100644 --- a/i18n/ja/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/bns-contract.md +++ b/i18n/ja/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/bns-contract.md @@ -1,13 +1,13 @@ --- title: BNS Contract -description: The Blockchain Naming System. +description: The Bitcoin Naming System. --- ![](/img/satoshi-btc.png) ## Introduction -The Blockchain Naming System (BNS) is implemented as a smart contract using Clarity. +The Bitcoin 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: From f2036af05e902988078bd4cc93bcfe612daadfca Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Fri, 10 Feb 2023 16:01:54 +0100 Subject: [PATCH 0846/1444] New translations bns-contract.md (Korean) --- .../current/clarity/noteworthy-contracts/bns-contract.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/i18n/ko/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/bns-contract.md b/i18n/ko/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/bns-contract.md index a7770b7d24..9e92bd758a 100644 --- a/i18n/ko/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/bns-contract.md +++ b/i18n/ko/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/bns-contract.md @@ -1,13 +1,13 @@ --- title: BNS Contract -description: The Blockchain Naming System. +description: The Bitcoin Naming System. --- ![](/img/satoshi-btc.png) ## Introduction -The Blockchain Naming System (BNS) is implemented as a smart contract using Clarity. +The Bitcoin 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: From 84f0206536d889893f488856e499e939a52b405d Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Fri, 10 Feb 2023 16:01:55 +0100 Subject: [PATCH 0847/1444] New translations bns-contract.md (Russian) --- .../current/clarity/noteworthy-contracts/bns-contract.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/bns-contract.md b/i18n/ru/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/bns-contract.md index a7770b7d24..9e92bd758a 100644 --- a/i18n/ru/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/bns-contract.md +++ b/i18n/ru/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/bns-contract.md @@ -1,13 +1,13 @@ --- title: BNS Contract -description: The Blockchain Naming System. +description: The Bitcoin Naming System. --- ![](/img/satoshi-btc.png) ## Introduction -The Blockchain Naming System (BNS) is implemented as a smart contract using Clarity. +The Bitcoin 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: From df2461469e9656efde9b3d8fbe13f4edb85f3120 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Fri, 10 Feb 2023 16:01:56 +0100 Subject: [PATCH 0848/1444] New translations bns-contract.md (Turkish) --- .../current/clarity/noteworthy-contracts/bns-contract.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/i18n/tr/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/bns-contract.md b/i18n/tr/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/bns-contract.md index a7770b7d24..9e92bd758a 100644 --- a/i18n/tr/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/bns-contract.md +++ b/i18n/tr/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/bns-contract.md @@ -1,13 +1,13 @@ --- title: BNS Contract -description: The Blockchain Naming System. +description: The Bitcoin Naming System. --- ![](/img/satoshi-btc.png) ## Introduction -The Blockchain Naming System (BNS) is implemented as a smart contract using Clarity. +The Bitcoin 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: From 052aef6d287572c46bed7028211e8b257bd790c0 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Fri, 10 Feb 2023 16:01:57 +0100 Subject: [PATCH 0849/1444] New translations bns-contract.md (Chinese Simplified) --- .../current/clarity/noteworthy-contracts/bns-contract.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/bns-contract.md b/i18n/zh/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/bns-contract.md index a7770b7d24..9e92bd758a 100644 --- a/i18n/zh/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/bns-contract.md +++ b/i18n/zh/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/bns-contract.md @@ -1,13 +1,13 @@ --- title: BNS Contract -description: The Blockchain Naming System. +description: The Bitcoin Naming System. --- ![](/img/satoshi-btc.png) ## Introduction -The Blockchain Naming System (BNS) is implemented as a smart contract using Clarity. +The Bitcoin 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: From 7a02ba62827dfd0b578d3465a78ce34eb3db7083 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Fri, 10 Feb 2023 16:01:59 +0100 Subject: [PATCH 0850/1444] New translations bns-contract.md (Vietnamese) --- .../current/clarity/noteworthy-contracts/bns-contract.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/i18n/vi/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/bns-contract.md b/i18n/vi/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/bns-contract.md index a7770b7d24..9e92bd758a 100644 --- a/i18n/vi/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/bns-contract.md +++ b/i18n/vi/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/bns-contract.md @@ -1,13 +1,13 @@ --- title: BNS Contract -description: The Blockchain Naming System. +description: The Bitcoin Naming System. --- ![](/img/satoshi-btc.png) ## Introduction -The Blockchain Naming System (BNS) is implemented as a smart contract using Clarity. +The Bitcoin 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: From 4d618f10d81d76b25a6444ca37002f6d5cab7a76 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Fri, 10 Feb 2023 16:02:00 +0100 Subject: [PATCH 0851/1444] New translations bns-contract.md (Portuguese, Brazilian) --- .../current/clarity/noteworthy-contracts/bns-contract.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/i18n/pt/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/bns-contract.md b/i18n/pt/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/bns-contract.md index a7770b7d24..9e92bd758a 100644 --- a/i18n/pt/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/bns-contract.md +++ b/i18n/pt/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/bns-contract.md @@ -1,13 +1,13 @@ --- title: BNS Contract -description: The Blockchain Naming System. +description: The Bitcoin Naming System. --- ![](/img/satoshi-btc.png) ## Introduction -The Blockchain Naming System (BNS) is implemented as a smart contract using Clarity. +The Bitcoin 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: From a35eb0946fbdde080e8bc6a045905ddbef3a66c2 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Fri, 10 Feb 2023 16:02:01 +0100 Subject: [PATCH 0852/1444] New translations bns-contract.md (Indonesian) --- .../current/clarity/noteworthy-contracts/bns-contract.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/i18n/id/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/bns-contract.md b/i18n/id/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/bns-contract.md index a500af3f22..d87d75d423 100644 --- a/i18n/id/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/bns-contract.md +++ b/i18n/id/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/bns-contract.md @@ -1,13 +1,13 @@ --- title: BNS Contract -description: The Blockchain Naming System. +description: The Bitcoin Naming System. --- ![](/img/satoshi-btc.png) ## Pengantar -The Blockchain Naming System (BNS) is implemented as a smart contract using Clarity. +The Bitcoin 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: From 0bc3bb29f2e2530c97e46641b0cc2c7df8050966 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Fri, 10 Feb 2023 16:02:02 +0100 Subject: [PATCH 0853/1444] New translations bns-contract.md (Hindi) --- .../current/clarity/noteworthy-contracts/bns-contract.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/i18n/hi/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/bns-contract.md b/i18n/hi/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/bns-contract.md index a7770b7d24..9e92bd758a 100644 --- a/i18n/hi/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/bns-contract.md +++ b/i18n/hi/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/bns-contract.md @@ -1,13 +1,13 @@ --- title: BNS Contract -description: The Blockchain Naming System. +description: The Bitcoin Naming System. --- ![](/img/satoshi-btc.png) ## Introduction -The Blockchain Naming System (BNS) is implemented as a smart contract using Clarity. +The Bitcoin 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: From 16c100422b674bcbf7be29bb85c55ce66c1791c1 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Fri, 10 Feb 2023 20:26:19 +0100 Subject: [PATCH 0854/1444] Update source file bns-contract.md --- docs/clarity/noteworthy-contracts/bns-contract.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/clarity/noteworthy-contracts/bns-contract.md b/docs/clarity/noteworthy-contracts/bns-contract.md index 4b5df1b386..dae5efb997 100644 --- a/docs/clarity/noteworthy-contracts/bns-contract.md +++ b/docs/clarity/noteworthy-contracts/bns-contract.md @@ -1,13 +1,13 @@ --- title: BNS Contract -description: The Blockchain Naming System. +description: The Bitcoin Naming System. --- ![](/img/satoshi-btc.png) ## Introduction -The Blockchain Naming System (BNS) is implemented as a smart contract using Clarity. +The Bitcoin 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: From 252fea2fed746f75241146a196f524358d06c905 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Fri, 10 Feb 2023 20:27:30 +0100 Subject: [PATCH 0855/1444] New translations wallets.md (French) --- .../current/services-using-stacks/wallets.md | 6 ------ 1 file changed, 6 deletions(-) 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 index 2d3fcc85f2..80142a29d1 100644 --- 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 @@ -34,12 +34,6 @@ Please edit this page to add any relevant new site that we are missing. ![](/img/sh_hirowallet.png) -## Neptune - -[Neptune](https://neptunewallet.io) - -![](/img/sh_neptunewallet.png) - ## Xverse [Xverse](https://www.xverse.app/) From 4321f9cab9efd1f299c01454a88b3cf042908512 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Fri, 10 Feb 2023 20:28:14 +0100 Subject: [PATCH 0856/1444] New translations wallets.md (Spanish) --- .../current/services-using-stacks/wallets.md | 6 ------ 1 file changed, 6 deletions(-) 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 index 5fbeeecbff..de4f9339e7 100644 --- 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 @@ -34,12 +34,6 @@ Please edit this page to add any relevant new site that we are missing. ![](/img/sh_hirowallet.png) -## Neptune - -[Neptune](https://neptunewallet.io) - -![](/img/sh_neptunewallet.png) - ## Xverse [Xverse](https://www.xverse.app/) From 15b9d4c48433e9e8ad9ff630a966bfc2b5dcd5ec Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Fri, 10 Feb 2023 20:28:58 +0100 Subject: [PATCH 0857/1444] New translations wallets.md (German) --- .../current/services-using-stacks/wallets.md | 6 ------ 1 file changed, 6 deletions(-) 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 index 2d3fcc85f2..80142a29d1 100644 --- 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 @@ -34,12 +34,6 @@ Please edit this page to add any relevant new site that we are missing. ![](/img/sh_hirowallet.png) -## Neptune - -[Neptune](https://neptunewallet.io) - -![](/img/sh_neptunewallet.png) - ## Xverse [Xverse](https://www.xverse.app/) From 4556374412e711ebe823234eee4588a204254545 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Fri, 10 Feb 2023 20:29:43 +0100 Subject: [PATCH 0858/1444] New translations wallets.md (Japanese) --- .../current/services-using-stacks/wallets.md | 6 ------ 1 file changed, 6 deletions(-) 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 index 2d3fcc85f2..80142a29d1 100644 --- 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 @@ -34,12 +34,6 @@ Please edit this page to add any relevant new site that we are missing. ![](/img/sh_hirowallet.png) -## Neptune - -[Neptune](https://neptunewallet.io) - -![](/img/sh_neptunewallet.png) - ## Xverse [Xverse](https://www.xverse.app/) From f603fab8d0b8df4854ed8626396cdf58f2ea41ff Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Fri, 10 Feb 2023 20:30:29 +0100 Subject: [PATCH 0859/1444] New translations wallets.md (Korean) --- .../current/services-using-stacks/wallets.md | 6 ------ 1 file changed, 6 deletions(-) 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 index 2d3fcc85f2..80142a29d1 100644 --- 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 @@ -34,12 +34,6 @@ Please edit this page to add any relevant new site that we are missing. ![](/img/sh_hirowallet.png) -## Neptune - -[Neptune](https://neptunewallet.io) - -![](/img/sh_neptunewallet.png) - ## Xverse [Xverse](https://www.xverse.app/) From bf2d2a0403944ff67babd022fa201f2eff322a3a Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Fri, 10 Feb 2023 20:31:12 +0100 Subject: [PATCH 0860/1444] New translations wallets.md (Russian) --- .../current/services-using-stacks/wallets.md | 6 ------ 1 file changed, 6 deletions(-) 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 index 2d3fcc85f2..80142a29d1 100644 --- 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 @@ -34,12 +34,6 @@ Please edit this page to add any relevant new site that we are missing. ![](/img/sh_hirowallet.png) -## Neptune - -[Neptune](https://neptunewallet.io) - -![](/img/sh_neptunewallet.png) - ## Xverse [Xverse](https://www.xverse.app/) From 6814a72de3d05e04dd2f323b6b8ee6a807c591fe Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Fri, 10 Feb 2023 20:31:56 +0100 Subject: [PATCH 0861/1444] New translations wallets.md (Turkish) --- .../current/services-using-stacks/wallets.md | 6 ------ 1 file changed, 6 deletions(-) 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 index 2d3fcc85f2..80142a29d1 100644 --- 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 @@ -34,12 +34,6 @@ Please edit this page to add any relevant new site that we are missing. ![](/img/sh_hirowallet.png) -## Neptune - -[Neptune](https://neptunewallet.io) - -![](/img/sh_neptunewallet.png) - ## Xverse [Xverse](https://www.xverse.app/) From 473aff801ee06030d75976131fb40aa6ade9c431 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Fri, 10 Feb 2023 20:32:42 +0100 Subject: [PATCH 0862/1444] New translations wallets.md (Chinese Simplified) --- .../current/services-using-stacks/wallets.md | 6 ------ 1 file changed, 6 deletions(-) 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 index 2d3fcc85f2..80142a29d1 100644 --- 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 @@ -34,12 +34,6 @@ Please edit this page to add any relevant new site that we are missing. ![](/img/sh_hirowallet.png) -## Neptune - -[Neptune](https://neptunewallet.io) - -![](/img/sh_neptunewallet.png) - ## Xverse [Xverse](https://www.xverse.app/) From 003754f5c71c7d26d0a5d1b98d9ec866a329a210 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Fri, 10 Feb 2023 20:33:26 +0100 Subject: [PATCH 0863/1444] New translations wallets.md (Vietnamese) --- .../current/services-using-stacks/wallets.md | 6 ------ 1 file changed, 6 deletions(-) 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 index 2d3fcc85f2..80142a29d1 100644 --- 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 @@ -34,12 +34,6 @@ Please edit this page to add any relevant new site that we are missing. ![](/img/sh_hirowallet.png) -## Neptune - -[Neptune](https://neptunewallet.io) - -![](/img/sh_neptunewallet.png) - ## Xverse [Xverse](https://www.xverse.app/) From 6e0f3f68d3fba5a7a5579a3e1a69a1f9ed21d8ca Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Fri, 10 Feb 2023 20:34:11 +0100 Subject: [PATCH 0864/1444] New translations wallets.md (Portuguese, Brazilian) --- .../current/services-using-stacks/wallets.md | 6 ------ 1 file changed, 6 deletions(-) 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 index 2d3fcc85f2..80142a29d1 100644 --- 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 @@ -34,12 +34,6 @@ Please edit this page to add any relevant new site that we are missing. ![](/img/sh_hirowallet.png) -## Neptune - -[Neptune](https://neptunewallet.io) - -![](/img/sh_neptunewallet.png) - ## Xverse [Xverse](https://www.xverse.app/) From c13efe27718a145f5e77b2f9cb8d892b34caf56c Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Fri, 10 Feb 2023 20:34:54 +0100 Subject: [PATCH 0865/1444] New translations wallets.md (Indonesian) --- .../current/services-using-stacks/wallets.md | 6 ------ 1 file changed, 6 deletions(-) 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 index f942cd3b1f..42c916c43c 100644 --- 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 @@ -34,12 +34,6 @@ Please edit this page to add any relevant new site that we are missing. ![](/img/sh_hirowallet.png) -## Neptune - -[Neptune](https://neptunewallet.io) - -![](/img/sh_neptunewallet.png) - ## Xverse [Xverse](https://www.xverse.app/) From ac30dc56dea37e7c245386a684a6f6369da41afd Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Fri, 10 Feb 2023 20:35:38 +0100 Subject: [PATCH 0866/1444] New translations wallets.md (Hindi) --- .../current/services-using-stacks/wallets.md | 6 ------ 1 file changed, 6 deletions(-) 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 index 2d3fcc85f2..80142a29d1 100644 --- 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 @@ -34,12 +34,6 @@ Please edit this page to add any relevant new site that we are missing. ![](/img/sh_hirowallet.png) -## Neptune - -[Neptune](https://neptunewallet.io) - -![](/img/sh_neptunewallet.png) - ## Xverse [Xverse](https://www.xverse.app/) From 7aa12e04435851bd34cc10b845ffbc8ca9e11a58 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sat, 11 Feb 2023 02:05:28 +0100 Subject: [PATCH 0867/1444] Update source file wallets.md --- docs/services-using-stacks/wallets.md | 6 ------ 1 file changed, 6 deletions(-) diff --git a/docs/services-using-stacks/wallets.md b/docs/services-using-stacks/wallets.md index 2d3fcc85f2..80142a29d1 100644 --- a/docs/services-using-stacks/wallets.md +++ b/docs/services-using-stacks/wallets.md @@ -34,12 +34,6 @@ Please edit this page to add any relevant new site that we are missing. ![](/img/sh_hirowallet.png) -## Neptune - -[Neptune](https://neptunewallet.io) - -![](/img/sh_neptunewallet.png) - ## Xverse [Xverse](https://www.xverse.app/) From bd9fd1803f39b7b5eee57eeacc2a769a3e6e20e8 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sat, 11 Feb 2023 02:05:44 +0100 Subject: [PATCH 0868/1444] New translations bns.md (French) --- .../current/stacks-academy/bns.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/stacks-academy/bns.md b/i18n/fr/docusaurus-plugin-content-docs/current/stacks-academy/bns.md index 0a9426e088..759aa27343 100644 --- a/i18n/fr/docusaurus-plugin-content-docs/current/stacks-academy/bns.md +++ b/i18n/fr/docusaurus-plugin-content-docs/current/stacks-academy/bns.md @@ -1,10 +1,10 @@ --- -title: Système de nommage de la blockchain +title: Bitcoin Naming System description: Lier les noms d'utilisateur aux états hors chaîne sidebar_position: 8 --- -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. +Bitcoin Naming System (BNS) is a network system that binds Stacks usernames to off-chain state without relying on any central points of control. 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. From 69feb9d5effee839064fc2bbb7835a60e8996f1f Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sat, 11 Feb 2023 02:05:45 +0100 Subject: [PATCH 0869/1444] New translations bns.md (Spanish) --- .../current/stacks-academy/bns.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/i18n/es/docusaurus-plugin-content-docs/current/stacks-academy/bns.md b/i18n/es/docusaurus-plugin-content-docs/current/stacks-academy/bns.md index 30b43ca760..b89dcf0687 100644 --- a/i18n/es/docusaurus-plugin-content-docs/current/stacks-academy/bns.md +++ b/i18n/es/docusaurus-plugin-content-docs/current/stacks-academy/bns.md @@ -1,10 +1,10 @@ --- -title: Sistema de Nombres de Blockchain +title: Bitcoin Naming System description: Vincula los nombres de usuario de Stacks al estado off-chain sidebar_position: 8 --- -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. +Bitcoin Naming System (BNS) is a network system that binds Stacks usernames to off-chain state without relying on any central points of 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. From 2d66eba941156234e1bf06ea2f53434aacbe5ef4 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sat, 11 Feb 2023 02:05:46 +0100 Subject: [PATCH 0870/1444] New translations bns.md (German) --- .../current/stacks-academy/bns.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/i18n/de/docusaurus-plugin-content-docs/current/stacks-academy/bns.md b/i18n/de/docusaurus-plugin-content-docs/current/stacks-academy/bns.md index 4c89d9e56c..9c63307655 100644 --- a/i18n/de/docusaurus-plugin-content-docs/current/stacks-academy/bns.md +++ b/i18n/de/docusaurus-plugin-content-docs/current/stacks-academy/bns.md @@ -1,10 +1,10 @@ --- -title: Blockchain Naming System +title: Bitcoin Naming System description: Binds Stacks usernames to off-chain state sidebar_position: 8 --- -Blockchain Naming System (BNS) is a network system that binds Stacks usernames to off-chain state without relying on any central points of control. +Bitcoin 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. From 816c6024cb541846343ad7f99b43eeec69afb583 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sat, 11 Feb 2023 02:05:47 +0100 Subject: [PATCH 0871/1444] New translations bns.md (Japanese) --- .../current/stacks-academy/bns.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/stacks-academy/bns.md b/i18n/ja/docusaurus-plugin-content-docs/current/stacks-academy/bns.md index 4c89d9e56c..9c63307655 100644 --- a/i18n/ja/docusaurus-plugin-content-docs/current/stacks-academy/bns.md +++ b/i18n/ja/docusaurus-plugin-content-docs/current/stacks-academy/bns.md @@ -1,10 +1,10 @@ --- -title: Blockchain Naming System +title: Bitcoin Naming System description: Binds Stacks usernames to off-chain state sidebar_position: 8 --- -Blockchain Naming System (BNS) is a network system that binds Stacks usernames to off-chain state without relying on any central points of control. +Bitcoin 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. From 3f9b05e0a2474a77128e4626057648bf7fff0503 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sat, 11 Feb 2023 02:05:48 +0100 Subject: [PATCH 0872/1444] New translations bns.md (Korean) --- .../current/stacks-academy/bns.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/i18n/ko/docusaurus-plugin-content-docs/current/stacks-academy/bns.md b/i18n/ko/docusaurus-plugin-content-docs/current/stacks-academy/bns.md index 4c89d9e56c..9c63307655 100644 --- a/i18n/ko/docusaurus-plugin-content-docs/current/stacks-academy/bns.md +++ b/i18n/ko/docusaurus-plugin-content-docs/current/stacks-academy/bns.md @@ -1,10 +1,10 @@ --- -title: Blockchain Naming System +title: Bitcoin Naming System description: Binds Stacks usernames to off-chain state sidebar_position: 8 --- -Blockchain Naming System (BNS) is a network system that binds Stacks usernames to off-chain state without relying on any central points of control. +Bitcoin 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. From 4ae3cf28aac740f2112f71cd5ec30c08ae5f6ca5 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sat, 11 Feb 2023 02:05:49 +0100 Subject: [PATCH 0873/1444] New translations bns.md (Russian) --- .../current/stacks-academy/bns.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/stacks-academy/bns.md b/i18n/ru/docusaurus-plugin-content-docs/current/stacks-academy/bns.md index 4c89d9e56c..9c63307655 100644 --- a/i18n/ru/docusaurus-plugin-content-docs/current/stacks-academy/bns.md +++ b/i18n/ru/docusaurus-plugin-content-docs/current/stacks-academy/bns.md @@ -1,10 +1,10 @@ --- -title: Blockchain Naming System +title: Bitcoin Naming System description: Binds Stacks usernames to off-chain state sidebar_position: 8 --- -Blockchain Naming System (BNS) is a network system that binds Stacks usernames to off-chain state without relying on any central points of control. +Bitcoin 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. From 1a5b63b545afc916013c5acf9b743c3958982ce2 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sat, 11 Feb 2023 02:05:50 +0100 Subject: [PATCH 0874/1444] New translations bns.md (Turkish) --- .../current/stacks-academy/bns.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/i18n/tr/docusaurus-plugin-content-docs/current/stacks-academy/bns.md b/i18n/tr/docusaurus-plugin-content-docs/current/stacks-academy/bns.md index 4c89d9e56c..9c63307655 100644 --- a/i18n/tr/docusaurus-plugin-content-docs/current/stacks-academy/bns.md +++ b/i18n/tr/docusaurus-plugin-content-docs/current/stacks-academy/bns.md @@ -1,10 +1,10 @@ --- -title: Blockchain Naming System +title: Bitcoin Naming System description: Binds Stacks usernames to off-chain state sidebar_position: 8 --- -Blockchain Naming System (BNS) is a network system that binds Stacks usernames to off-chain state without relying on any central points of control. +Bitcoin 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. From 4fa5b1f6651a86e567f7c9bddf957eabd7eb2584 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sat, 11 Feb 2023 02:05:51 +0100 Subject: [PATCH 0875/1444] New translations bns.md (Chinese Simplified) --- .../current/stacks-academy/bns.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/stacks-academy/bns.md b/i18n/zh/docusaurus-plugin-content-docs/current/stacks-academy/bns.md index e09390aefe..e67703908a 100644 --- a/i18n/zh/docusaurus-plugin-content-docs/current/stacks-academy/bns.md +++ b/i18n/zh/docusaurus-plugin-content-docs/current/stacks-academy/bns.md @@ -1,10 +1,10 @@ --- -title: Blockchain Naming System +title: Bitcoin Naming System description: Binds Stacks usernames to off-chain state sidebar_position: 8 --- -Blockchain Naming System (BNS) is a network system that binds Stacks usernames to off-chain state without relying on any central points of control. +Bitcoin 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. From 19c3d8598a13c38b0b0e7e479249568eeded3de9 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sat, 11 Feb 2023 02:05:52 +0100 Subject: [PATCH 0876/1444] New translations bns.md (Vietnamese) --- .../current/stacks-academy/bns.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/i18n/vi/docusaurus-plugin-content-docs/current/stacks-academy/bns.md b/i18n/vi/docusaurus-plugin-content-docs/current/stacks-academy/bns.md index 4c89d9e56c..9c63307655 100644 --- a/i18n/vi/docusaurus-plugin-content-docs/current/stacks-academy/bns.md +++ b/i18n/vi/docusaurus-plugin-content-docs/current/stacks-academy/bns.md @@ -1,10 +1,10 @@ --- -title: Blockchain Naming System +title: Bitcoin Naming System description: Binds Stacks usernames to off-chain state sidebar_position: 8 --- -Blockchain Naming System (BNS) is a network system that binds Stacks usernames to off-chain state without relying on any central points of control. +Bitcoin 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. From ffc4657baee30bb829324a24406a1833ac0010b3 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sat, 11 Feb 2023 02:05:53 +0100 Subject: [PATCH 0877/1444] New translations bns.md (Portuguese, Brazilian) --- .../current/stacks-academy/bns.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/i18n/pt/docusaurus-plugin-content-docs/current/stacks-academy/bns.md b/i18n/pt/docusaurus-plugin-content-docs/current/stacks-academy/bns.md index d105ef69cf..082ebe8b80 100644 --- a/i18n/pt/docusaurus-plugin-content-docs/current/stacks-academy/bns.md +++ b/i18n/pt/docusaurus-plugin-content-docs/current/stacks-academy/bns.md @@ -1,10 +1,10 @@ --- -title: Blockchain Naming System +title: Bitcoin Naming System description: Binds Stacks usernames to off-chain state sidebar_position: 8 --- -Blockchain Naming System (BNS) is a network system that binds Stacks usernames to off-chain state without relying on any central points of control. +Bitcoin 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. From 1c3c2e35754391ea4c5ca06fd48e6afba757dd15 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sat, 11 Feb 2023 02:05:54 +0100 Subject: [PATCH 0878/1444] New translations bns.md (Indonesian) --- .../current/stacks-academy/bns.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/i18n/id/docusaurus-plugin-content-docs/current/stacks-academy/bns.md b/i18n/id/docusaurus-plugin-content-docs/current/stacks-academy/bns.md index c9c8ac533a..6c92759a79 100644 --- a/i18n/id/docusaurus-plugin-content-docs/current/stacks-academy/bns.md +++ b/i18n/id/docusaurus-plugin-content-docs/current/stacks-academy/bns.md @@ -1,10 +1,10 @@ --- -title: Sistem Penamaan Blockchain +title: Bitcoin Naming System description: Mengikat nama pengguna Stacks ke status luar-rantai sidebar_position: 8 --- -Blockchain Naming System (BNS) is a network system that binds Stacks usernames to off-chain state without relying on any central points of control. +Bitcoin 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. From 51e0800e469855fb0af4508b77228d048637cadf Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sat, 11 Feb 2023 02:05:55 +0100 Subject: [PATCH 0879/1444] New translations bns.md (Hindi) --- .../current/stacks-academy/bns.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/i18n/hi/docusaurus-plugin-content-docs/current/stacks-academy/bns.md b/i18n/hi/docusaurus-plugin-content-docs/current/stacks-academy/bns.md index 4c89d9e56c..9c63307655 100644 --- a/i18n/hi/docusaurus-plugin-content-docs/current/stacks-academy/bns.md +++ b/i18n/hi/docusaurus-plugin-content-docs/current/stacks-academy/bns.md @@ -1,10 +1,10 @@ --- -title: Blockchain Naming System +title: Bitcoin Naming System description: Binds Stacks usernames to off-chain state sidebar_position: 8 --- -Blockchain Naming System (BNS) is a network system that binds Stacks usernames to off-chain state without relying on any central points of control. +Bitcoin 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. From 690d0f706716413af14945f11259f5c48a6fe14a Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sat, 11 Feb 2023 19:58:04 +0100 Subject: [PATCH 0880/1444] Update source file bns.md --- docs/stacks-academy/bns.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/stacks-academy/bns.md b/docs/stacks-academy/bns.md index f0605d1841..6d600ff6f4 100644 --- a/docs/stacks-academy/bns.md +++ b/docs/stacks-academy/bns.md @@ -1,10 +1,10 @@ --- -title: Blockchain Naming System +title: Bitcoin Naming System description: Binds Stacks usernames to off-chain state sidebar_position: 8 --- -Blockchain Naming System (BNS) is a network system that binds Stacks usernames +Bitcoin 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. From 6d8702aae0bc5d7419ff4d77f868ac918eb45e81 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sat, 11 Feb 2023 19:58:22 +0100 Subject: [PATCH 0881/1444] New translations bns.md (French) --- .../current/stacks-academy/bns.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/stacks-academy/bns.md b/i18n/fr/docusaurus-plugin-content-docs/current/stacks-academy/bns.md index 759aa27343..a64344f3f0 100644 --- a/i18n/fr/docusaurus-plugin-content-docs/current/stacks-academy/bns.md +++ b/i18n/fr/docusaurus-plugin-content-docs/current/stacks-academy/bns.md @@ -1,10 +1,10 @@ --- -title: Bitcoin Naming System +title: Bitcoin Name System description: Lier les noms d'utilisateur aux états hors chaîne sidebar_position: 8 --- -Bitcoin Naming System (BNS) is a network system that binds Stacks usernames to off-chain state without relying on any central points of control. +Bitcoin Name System (BNS) is a network system that binds Stacks usernames to off-chain state without relying on any central points of control. 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. @@ -18,9 +18,9 @@ La blockchain Stacks assure que la vue BNS de chaque nœud est synchronisée ave 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 +## Motivation behind name systems -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. +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. 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é. @@ -70,7 +70,7 @@ Une matrice de comparaison de fonctionnalités résumant les similitudes et les ## Espaces de nommage -Les espaces de noms sont les objets de nommage de premier niveau dans BNS. +Namespaces are the top-level name objects in BNS. Ils contrôlent quelques propriétés inhérentes aux noms : From 36fa99dd18d74ed64188ec91dd41ce5359036fac Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sat, 11 Feb 2023 19:58:23 +0100 Subject: [PATCH 0882/1444] New translations bns-contract.md (French) --- .../current/clarity/noteworthy-contracts/bns-contract.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/bns-contract.md b/i18n/fr/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/bns-contract.md index 9e92bd758a..13a0198924 100644 --- a/i18n/fr/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/bns-contract.md +++ b/i18n/fr/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/bns-contract.md @@ -1,13 +1,13 @@ --- title: BNS Contract -description: The Bitcoin Naming System. +description: The Bitcoin Name System. --- ![](/img/satoshi-btc.png) ## Introduction -The Bitcoin Naming System (BNS) is implemented as a smart contract using Clarity. +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: From d7c95d37cc2d47436c52b054580f89e58eff15cb Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sat, 11 Feb 2023 19:58:24 +0100 Subject: [PATCH 0883/1444] New translations bns.md (Spanish) --- .../current/stacks-academy/bns.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/i18n/es/docusaurus-plugin-content-docs/current/stacks-academy/bns.md b/i18n/es/docusaurus-plugin-content-docs/current/stacks-academy/bns.md index b89dcf0687..746fe290a3 100644 --- a/i18n/es/docusaurus-plugin-content-docs/current/stacks-academy/bns.md +++ b/i18n/es/docusaurus-plugin-content-docs/current/stacks-academy/bns.md @@ -1,10 +1,10 @@ --- -title: Bitcoin Naming System +title: Bitcoin Name System description: Vincula los nombres de usuario de Stacks al estado off-chain sidebar_position: 8 --- -Bitcoin Naming System (BNS) is a network system that binds Stacks usernames to off-chain state without relying on any central points of control. +Bitcoin Name System (BNS) is a network system that binds Stacks usernames to off-chain state without relying on any central points of 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. @@ -18,9 +18,9 @@ La blockchain de Stacks asegura que la vista del BNS de cada nodo está sincroni 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 +## Motivation behind name systems -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. +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. 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. @@ -70,7 +70,7 @@ Una matriz de comparación de características que resume las similitudes y dife ## Namespaces -Los namespaces son los objetos de nombre de nivel superior en BNS. +Namespaces are the top-level name objects in BNS. Controlan algunas propiedades de los nombres que contienen: From 9d0ed32c51ac77cf53aa0299932a9d83ac81045d Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sat, 11 Feb 2023 19:58:25 +0100 Subject: [PATCH 0884/1444] New translations bns-contract.md (Spanish) --- .../current/clarity/noteworthy-contracts/bns-contract.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/i18n/es/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/bns-contract.md b/i18n/es/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/bns-contract.md index cb13d48016..8f0849b1dd 100644 --- a/i18n/es/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/bns-contract.md +++ b/i18n/es/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/bns-contract.md @@ -1,13 +1,13 @@ --- title: BNS Contract -description: The Bitcoin Naming System. +description: The Bitcoin Name System. --- ![](/img/satoshi-btc.png) ## Introducción -The Bitcoin Naming System (BNS) is implemented as a smart contract using Clarity. +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: From 0fd86e410ae07189ef76cb796764ece1766ace29 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sat, 11 Feb 2023 19:58:26 +0100 Subject: [PATCH 0885/1444] New translations bns.md (German) --- .../current/stacks-academy/bns.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/i18n/de/docusaurus-plugin-content-docs/current/stacks-academy/bns.md b/i18n/de/docusaurus-plugin-content-docs/current/stacks-academy/bns.md index 9c63307655..8eb4f39376 100644 --- a/i18n/de/docusaurus-plugin-content-docs/current/stacks-academy/bns.md +++ b/i18n/de/docusaurus-plugin-content-docs/current/stacks-academy/bns.md @@ -1,10 +1,10 @@ --- -title: Bitcoin Naming System +title: Bitcoin Name System description: Binds Stacks usernames to off-chain state sidebar_position: 8 --- -Bitcoin Naming System (BNS) is a network system that binds Stacks usernames to off-chain state without relying on any central points of control. +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. @@ -18,9 +18,9 @@ The Stacks blockchain insures that each node's BNS view is synchronized to all o 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 +## Motivation behind name 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. +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. @@ -70,7 +70,7 @@ A feature comparison matrix summarizing the similarities and differences between ## Namespaces -Namespaces are the top-level naming objects in BNS. +Namespaces are the top-level name objects in BNS. They control a few properties about the names within them: From 9752173880c1b87baf48432fd710321ddd12028a Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sat, 11 Feb 2023 19:58:27 +0100 Subject: [PATCH 0886/1444] New translations bns-contract.md (German) --- .../current/clarity/noteworthy-contracts/bns-contract.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/i18n/de/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/bns-contract.md b/i18n/de/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/bns-contract.md index 9e92bd758a..13a0198924 100644 --- a/i18n/de/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/bns-contract.md +++ b/i18n/de/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/bns-contract.md @@ -1,13 +1,13 @@ --- title: BNS Contract -description: The Bitcoin Naming System. +description: The Bitcoin Name System. --- ![](/img/satoshi-btc.png) ## Introduction -The Bitcoin Naming System (BNS) is implemented as a smart contract using Clarity. +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: From 58193f72201aec0629aaf769810f2dc649529478 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sat, 11 Feb 2023 19:58:28 +0100 Subject: [PATCH 0887/1444] New translations bns.md (Japanese) --- .../current/stacks-academy/bns.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/stacks-academy/bns.md b/i18n/ja/docusaurus-plugin-content-docs/current/stacks-academy/bns.md index 9c63307655..8eb4f39376 100644 --- a/i18n/ja/docusaurus-plugin-content-docs/current/stacks-academy/bns.md +++ b/i18n/ja/docusaurus-plugin-content-docs/current/stacks-academy/bns.md @@ -1,10 +1,10 @@ --- -title: Bitcoin Naming System +title: Bitcoin Name System description: Binds Stacks usernames to off-chain state sidebar_position: 8 --- -Bitcoin Naming System (BNS) is a network system that binds Stacks usernames to off-chain state without relying on any central points of control. +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. @@ -18,9 +18,9 @@ The Stacks blockchain insures that each node's BNS view is synchronized to all o 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 +## Motivation behind name 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. +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. @@ -70,7 +70,7 @@ A feature comparison matrix summarizing the similarities and differences between ## Namespaces -Namespaces are the top-level naming objects in BNS. +Namespaces are the top-level name objects in BNS. They control a few properties about the names within them: From 6d814ad5380d2274852c65388a7adfd4389053fb Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sat, 11 Feb 2023 19:58:29 +0100 Subject: [PATCH 0888/1444] New translations bns-contract.md (Japanese) --- .../current/clarity/noteworthy-contracts/bns-contract.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/bns-contract.md b/i18n/ja/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/bns-contract.md index 9e92bd758a..13a0198924 100644 --- a/i18n/ja/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/bns-contract.md +++ b/i18n/ja/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/bns-contract.md @@ -1,13 +1,13 @@ --- title: BNS Contract -description: The Bitcoin Naming System. +description: The Bitcoin Name System. --- ![](/img/satoshi-btc.png) ## Introduction -The Bitcoin Naming System (BNS) is implemented as a smart contract using Clarity. +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: From 080557dadddb9473ace7ed29aaf0d62b9cb61b7a Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sat, 11 Feb 2023 19:58:30 +0100 Subject: [PATCH 0889/1444] New translations bns.md (Korean) --- .../current/stacks-academy/bns.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/i18n/ko/docusaurus-plugin-content-docs/current/stacks-academy/bns.md b/i18n/ko/docusaurus-plugin-content-docs/current/stacks-academy/bns.md index 9c63307655..8eb4f39376 100644 --- a/i18n/ko/docusaurus-plugin-content-docs/current/stacks-academy/bns.md +++ b/i18n/ko/docusaurus-plugin-content-docs/current/stacks-academy/bns.md @@ -1,10 +1,10 @@ --- -title: Bitcoin Naming System +title: Bitcoin Name System description: Binds Stacks usernames to off-chain state sidebar_position: 8 --- -Bitcoin Naming System (BNS) is a network system that binds Stacks usernames to off-chain state without relying on any central points of control. +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. @@ -18,9 +18,9 @@ The Stacks blockchain insures that each node's BNS view is synchronized to all o 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 +## Motivation behind name 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. +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. @@ -70,7 +70,7 @@ A feature comparison matrix summarizing the similarities and differences between ## Namespaces -Namespaces are the top-level naming objects in BNS. +Namespaces are the top-level name objects in BNS. They control a few properties about the names within them: From cc16a81e1ab1b349c84965758ae66c70d0891517 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sat, 11 Feb 2023 19:58:31 +0100 Subject: [PATCH 0890/1444] New translations bns-contract.md (Korean) --- .../current/clarity/noteworthy-contracts/bns-contract.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/i18n/ko/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/bns-contract.md b/i18n/ko/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/bns-contract.md index 9e92bd758a..13a0198924 100644 --- a/i18n/ko/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/bns-contract.md +++ b/i18n/ko/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/bns-contract.md @@ -1,13 +1,13 @@ --- title: BNS Contract -description: The Bitcoin Naming System. +description: The Bitcoin Name System. --- ![](/img/satoshi-btc.png) ## Introduction -The Bitcoin Naming System (BNS) is implemented as a smart contract using Clarity. +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: From d9c6151f615d35d4af8287002428c7ce215f640d Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sat, 11 Feb 2023 19:58:32 +0100 Subject: [PATCH 0891/1444] New translations bns.md (Russian) --- .../current/stacks-academy/bns.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/stacks-academy/bns.md b/i18n/ru/docusaurus-plugin-content-docs/current/stacks-academy/bns.md index 9c63307655..8eb4f39376 100644 --- a/i18n/ru/docusaurus-plugin-content-docs/current/stacks-academy/bns.md +++ b/i18n/ru/docusaurus-plugin-content-docs/current/stacks-academy/bns.md @@ -1,10 +1,10 @@ --- -title: Bitcoin Naming System +title: Bitcoin Name System description: Binds Stacks usernames to off-chain state sidebar_position: 8 --- -Bitcoin Naming System (BNS) is a network system that binds Stacks usernames to off-chain state without relying on any central points of control. +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. @@ -18,9 +18,9 @@ The Stacks blockchain insures that each node's BNS view is synchronized to all o 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 +## Motivation behind name 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. +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. @@ -70,7 +70,7 @@ A feature comparison matrix summarizing the similarities and differences between ## Namespaces -Namespaces are the top-level naming objects in BNS. +Namespaces are the top-level name objects in BNS. They control a few properties about the names within them: From 89cb40ae8ce4b2d9dd99fd5d1557db1a3427cd1d Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sat, 11 Feb 2023 19:58:34 +0100 Subject: [PATCH 0892/1444] New translations bns-contract.md (Russian) --- .../current/clarity/noteworthy-contracts/bns-contract.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/bns-contract.md b/i18n/ru/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/bns-contract.md index 9e92bd758a..13a0198924 100644 --- a/i18n/ru/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/bns-contract.md +++ b/i18n/ru/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/bns-contract.md @@ -1,13 +1,13 @@ --- title: BNS Contract -description: The Bitcoin Naming System. +description: The Bitcoin Name System. --- ![](/img/satoshi-btc.png) ## Introduction -The Bitcoin Naming System (BNS) is implemented as a smart contract using Clarity. +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: From 594503db629b5dd427ef9042c1dfab5211779c9c Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sat, 11 Feb 2023 19:58:35 +0100 Subject: [PATCH 0893/1444] New translations bns.md (Turkish) --- .../current/stacks-academy/bns.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/i18n/tr/docusaurus-plugin-content-docs/current/stacks-academy/bns.md b/i18n/tr/docusaurus-plugin-content-docs/current/stacks-academy/bns.md index 9c63307655..8eb4f39376 100644 --- a/i18n/tr/docusaurus-plugin-content-docs/current/stacks-academy/bns.md +++ b/i18n/tr/docusaurus-plugin-content-docs/current/stacks-academy/bns.md @@ -1,10 +1,10 @@ --- -title: Bitcoin Naming System +title: Bitcoin Name System description: Binds Stacks usernames to off-chain state sidebar_position: 8 --- -Bitcoin Naming System (BNS) is a network system that binds Stacks usernames to off-chain state without relying on any central points of control. +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. @@ -18,9 +18,9 @@ The Stacks blockchain insures that each node's BNS view is synchronized to all o 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 +## Motivation behind name 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. +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. @@ -70,7 +70,7 @@ A feature comparison matrix summarizing the similarities and differences between ## Namespaces -Namespaces are the top-level naming objects in BNS. +Namespaces are the top-level name objects in BNS. They control a few properties about the names within them: From 002abbf5c87769b31a767e978b78e80c28c6de8c Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sat, 11 Feb 2023 19:58:36 +0100 Subject: [PATCH 0894/1444] New translations bns-contract.md (Turkish) --- .../current/clarity/noteworthy-contracts/bns-contract.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/i18n/tr/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/bns-contract.md b/i18n/tr/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/bns-contract.md index 9e92bd758a..13a0198924 100644 --- a/i18n/tr/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/bns-contract.md +++ b/i18n/tr/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/bns-contract.md @@ -1,13 +1,13 @@ --- title: BNS Contract -description: The Bitcoin Naming System. +description: The Bitcoin Name System. --- ![](/img/satoshi-btc.png) ## Introduction -The Bitcoin Naming System (BNS) is implemented as a smart contract using Clarity. +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: From 14cc003537f1d46ae064e8e7ad6863b056cc66a7 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sat, 11 Feb 2023 19:58:37 +0100 Subject: [PATCH 0895/1444] New translations bns.md (Chinese Simplified) --- .../current/stacks-academy/bns.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/stacks-academy/bns.md b/i18n/zh/docusaurus-plugin-content-docs/current/stacks-academy/bns.md index e67703908a..a217b1b38b 100644 --- a/i18n/zh/docusaurus-plugin-content-docs/current/stacks-academy/bns.md +++ b/i18n/zh/docusaurus-plugin-content-docs/current/stacks-academy/bns.md @@ -1,10 +1,10 @@ --- -title: Bitcoin Naming System +title: Bitcoin Name System description: Binds Stacks usernames to off-chain state sidebar_position: 8 --- -Bitcoin Naming System (BNS) is a network system that binds Stacks usernames to off-chain state without relying on any central points of control. +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. 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. @@ -18,9 +18,9 @@ The Stacks blockchain insures that each node's BNS view is synchronized to all o 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 +## Motivation behind name 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. +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. 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. @@ -70,7 +70,7 @@ A feature comparison matrix summarizing the similarities and differences between ## Namespaces -Namespaces are the top-level naming objects in BNS. +Namespaces are the top-level name objects in BNS. They control a few properties about the names within them: From c1a2326b2c96827021a2fca7af93004203adee0c Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sat, 11 Feb 2023 19:58:38 +0100 Subject: [PATCH 0896/1444] New translations bns-contract.md (Chinese Simplified) --- .../current/clarity/noteworthy-contracts/bns-contract.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/bns-contract.md b/i18n/zh/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/bns-contract.md index 9e92bd758a..13a0198924 100644 --- a/i18n/zh/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/bns-contract.md +++ b/i18n/zh/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/bns-contract.md @@ -1,13 +1,13 @@ --- title: BNS Contract -description: The Bitcoin Naming System. +description: The Bitcoin Name System. --- ![](/img/satoshi-btc.png) ## Introduction -The Bitcoin Naming System (BNS) is implemented as a smart contract using Clarity. +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: From 6385052fa531309d4a90a40721d008c3d8e06735 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sat, 11 Feb 2023 19:58:39 +0100 Subject: [PATCH 0897/1444] New translations bns.md (Vietnamese) --- .../current/stacks-academy/bns.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/i18n/vi/docusaurus-plugin-content-docs/current/stacks-academy/bns.md b/i18n/vi/docusaurus-plugin-content-docs/current/stacks-academy/bns.md index 9c63307655..8eb4f39376 100644 --- a/i18n/vi/docusaurus-plugin-content-docs/current/stacks-academy/bns.md +++ b/i18n/vi/docusaurus-plugin-content-docs/current/stacks-academy/bns.md @@ -1,10 +1,10 @@ --- -title: Bitcoin Naming System +title: Bitcoin Name System description: Binds Stacks usernames to off-chain state sidebar_position: 8 --- -Bitcoin Naming System (BNS) is a network system that binds Stacks usernames to off-chain state without relying on any central points of control. +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. @@ -18,9 +18,9 @@ The Stacks blockchain insures that each node's BNS view is synchronized to all o 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 +## Motivation behind name 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. +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. @@ -70,7 +70,7 @@ A feature comparison matrix summarizing the similarities and differences between ## Namespaces -Namespaces are the top-level naming objects in BNS. +Namespaces are the top-level name objects in BNS. They control a few properties about the names within them: From b7590b31f6be87f95450bf5cbec2868d6e1b991c Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sat, 11 Feb 2023 19:58:40 +0100 Subject: [PATCH 0898/1444] New translations bns-contract.md (Vietnamese) --- .../current/clarity/noteworthy-contracts/bns-contract.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/i18n/vi/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/bns-contract.md b/i18n/vi/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/bns-contract.md index 9e92bd758a..13a0198924 100644 --- a/i18n/vi/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/bns-contract.md +++ b/i18n/vi/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/bns-contract.md @@ -1,13 +1,13 @@ --- title: BNS Contract -description: The Bitcoin Naming System. +description: The Bitcoin Name System. --- ![](/img/satoshi-btc.png) ## Introduction -The Bitcoin Naming System (BNS) is implemented as a smart contract using Clarity. +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: From 600cd08f253d603085cdb0a0f621914fc41a8dc7 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sat, 11 Feb 2023 19:58:41 +0100 Subject: [PATCH 0899/1444] New translations bns.md (Portuguese, Brazilian) --- .../current/stacks-academy/bns.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/i18n/pt/docusaurus-plugin-content-docs/current/stacks-academy/bns.md b/i18n/pt/docusaurus-plugin-content-docs/current/stacks-academy/bns.md index 082ebe8b80..8d4d3b54f8 100644 --- a/i18n/pt/docusaurus-plugin-content-docs/current/stacks-academy/bns.md +++ b/i18n/pt/docusaurus-plugin-content-docs/current/stacks-academy/bns.md @@ -1,10 +1,10 @@ --- -title: Bitcoin Naming System +title: Bitcoin Name System description: Binds Stacks usernames to off-chain state sidebar_position: 8 --- -Bitcoin Naming System (BNS) is a network system that binds Stacks usernames to off-chain state without relying on any central points of control. +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. @@ -18,9 +18,9 @@ The Stacks blockchain insures that each node's BNS view is synchronized to all o 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 +## Motivation behind name 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. +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. @@ -70,7 +70,7 @@ A feature comparison matrix summarizing the similarities and differences between ## Namespaces -Namespaces are the top-level naming objects in BNS. +Namespaces are the top-level name objects in BNS. They control a few properties about the names within them: From 74a255e0f8113e966294138e09e54ced53e1e8df Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sat, 11 Feb 2023 19:58:42 +0100 Subject: [PATCH 0900/1444] New translations bns-contract.md (Portuguese, Brazilian) --- .../current/clarity/noteworthy-contracts/bns-contract.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/i18n/pt/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/bns-contract.md b/i18n/pt/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/bns-contract.md index 9e92bd758a..13a0198924 100644 --- a/i18n/pt/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/bns-contract.md +++ b/i18n/pt/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/bns-contract.md @@ -1,13 +1,13 @@ --- title: BNS Contract -description: The Bitcoin Naming System. +description: The Bitcoin Name System. --- ![](/img/satoshi-btc.png) ## Introduction -The Bitcoin Naming System (BNS) is implemented as a smart contract using Clarity. +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: From 89694fdb724ad202f7c0660ffa70faec67d412e2 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sat, 11 Feb 2023 19:58:43 +0100 Subject: [PATCH 0901/1444] New translations bns.md (Indonesian) --- .../current/stacks-academy/bns.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/i18n/id/docusaurus-plugin-content-docs/current/stacks-academy/bns.md b/i18n/id/docusaurus-plugin-content-docs/current/stacks-academy/bns.md index 6c92759a79..98c1e81afb 100644 --- a/i18n/id/docusaurus-plugin-content-docs/current/stacks-academy/bns.md +++ b/i18n/id/docusaurus-plugin-content-docs/current/stacks-academy/bns.md @@ -1,10 +1,10 @@ --- -title: Bitcoin Naming System +title: Bitcoin Name System description: Mengikat nama pengguna Stacks ke status luar-rantai sidebar_position: 8 --- -Bitcoin Naming System (BNS) is a network system that binds Stacks usernames to off-chain state without relying on any central points of control. +Bitcoin Name 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. @@ -18,9 +18,9 @@ Blockchain Stacks memastikan bahwa tampilan BNS setiap noda disinkronkan ke semu 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 +## Motivation behind name systems -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. +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. 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. @@ -70,7 +70,7 @@ A feature comparison matrix summarizing the similarities and differences between ## Ruang nama -Ruang nama adalah objek penamaan level atas pada BNS. +Namespaces are the top-level name objects in BNS. Ruang nama mengontrol beberapa properti tentang nama-nama di dalamnya: From b4d3f6c8f6855aeee94cedbd7f5383e17dea24b0 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sat, 11 Feb 2023 19:58:44 +0100 Subject: [PATCH 0902/1444] New translations bns-contract.md (Indonesian) --- .../current/clarity/noteworthy-contracts/bns-contract.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/i18n/id/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/bns-contract.md b/i18n/id/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/bns-contract.md index d87d75d423..3e03181cd8 100644 --- a/i18n/id/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/bns-contract.md +++ b/i18n/id/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/bns-contract.md @@ -1,13 +1,13 @@ --- title: BNS Contract -description: The Bitcoin Naming System. +description: The Bitcoin Name System. --- ![](/img/satoshi-btc.png) ## Pengantar -The Bitcoin Naming System (BNS) is implemented as a smart contract using Clarity. +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: From f657526969f7ffdcf77c625823e6a17e2d8d6557 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sat, 11 Feb 2023 19:58:45 +0100 Subject: [PATCH 0903/1444] New translations bns.md (Hindi) --- .../current/stacks-academy/bns.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/i18n/hi/docusaurus-plugin-content-docs/current/stacks-academy/bns.md b/i18n/hi/docusaurus-plugin-content-docs/current/stacks-academy/bns.md index 9c63307655..8eb4f39376 100644 --- a/i18n/hi/docusaurus-plugin-content-docs/current/stacks-academy/bns.md +++ b/i18n/hi/docusaurus-plugin-content-docs/current/stacks-academy/bns.md @@ -1,10 +1,10 @@ --- -title: Bitcoin Naming System +title: Bitcoin Name System description: Binds Stacks usernames to off-chain state sidebar_position: 8 --- -Bitcoin Naming System (BNS) is a network system that binds Stacks usernames to off-chain state without relying on any central points of control. +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. @@ -18,9 +18,9 @@ The Stacks blockchain insures that each node's BNS view is synchronized to all o 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 +## Motivation behind name 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. +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. @@ -70,7 +70,7 @@ A feature comparison matrix summarizing the similarities and differences between ## Namespaces -Namespaces are the top-level naming objects in BNS. +Namespaces are the top-level name objects in BNS. They control a few properties about the names within them: From 294ebc9b4876da86391f7f1a9de3ea35b3fc0e59 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sat, 11 Feb 2023 19:58:46 +0100 Subject: [PATCH 0904/1444] New translations bns-contract.md (Hindi) --- .../current/clarity/noteworthy-contracts/bns-contract.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/i18n/hi/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/bns-contract.md b/i18n/hi/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/bns-contract.md index 9e92bd758a..13a0198924 100644 --- a/i18n/hi/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/bns-contract.md +++ b/i18n/hi/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/bns-contract.md @@ -1,13 +1,13 @@ --- title: BNS Contract -description: The Bitcoin Naming System. +description: The Bitcoin Name System. --- ![](/img/satoshi-btc.png) ## Introduction -The Bitcoin Naming System (BNS) is implemented as a smart contract using Clarity. +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: From 7eaaceb9d6691e5caa1e685d611b8929ede861fb Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Tue, 14 Feb 2023 21:15:15 +0100 Subject: [PATCH 0905/1444] Update source file bns-contract.md --- docs/clarity/noteworthy-contracts/bns-contract.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/clarity/noteworthy-contracts/bns-contract.md b/docs/clarity/noteworthy-contracts/bns-contract.md index dae5efb997..6dc73263a2 100644 --- a/docs/clarity/noteworthy-contracts/bns-contract.md +++ b/docs/clarity/noteworthy-contracts/bns-contract.md @@ -1,13 +1,13 @@ --- title: BNS Contract -description: The Bitcoin Naming System. +description: The Bitcoin Name System. --- ![](/img/satoshi-btc.png) ## Introduction -The Bitcoin Naming System (BNS) is implemented as a smart contract using Clarity. +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: From 5cbee0885f4d8f514e941f273908fa4e3863a817 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Tue, 14 Feb 2023 21:15:25 +0100 Subject: [PATCH 0906/1444] Update source file bns.md --- docs/stacks-academy/bns.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/stacks-academy/bns.md b/docs/stacks-academy/bns.md index 6d600ff6f4..c1257855a9 100644 --- a/docs/stacks-academy/bns.md +++ b/docs/stacks-academy/bns.md @@ -1,10 +1,10 @@ --- -title: Bitcoin Naming System +title: Bitcoin Name System description: Binds Stacks usernames to off-chain state sidebar_position: 8 --- -Bitcoin Naming System (BNS) is a network system that binds Stacks usernames +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. @@ -32,11 +32,11 @@ 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 +## Motivation behind name systems -We rely on naming systems in everyday life, and they play a critical +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 naming system to resolve +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 @@ -126,7 +126,7 @@ between these name objects is presented below: ## Namespaces -Namespaces are the top-level naming objects in BNS. +Namespaces are the top-level name objects in BNS. They control a few properties about the names within them: From ad29bd733f1b01b567fc508e8d3761fb8af4ef8a Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Tue, 14 Feb 2023 21:16:02 +0100 Subject: [PATCH 0907/1444] New translations what-is-stacks.md (French) --- .../current/stacks-academy/what-is-stacks.md | 39 +++++++------------ 1 file changed, 14 insertions(+), 25 deletions(-) diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/stacks-academy/what-is-stacks.md b/i18n/fr/docusaurus-plugin-content-docs/current/stacks-academy/what-is-stacks.md index 94277da8a9..abada2d864 100644 --- a/i18n/fr/docusaurus-plugin-content-docs/current/stacks-academy/what-is-stacks.md +++ b/i18n/fr/docusaurus-plugin-content-docs/current/stacks-academy/what-is-stacks.md @@ -10,26 +10,11 @@ We can get an idea of the goal and ethos behind Stacks by looking at [how Satosh > "...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. - -There's a lot of jargon, possible assumptions, controversy, and cool technology wrapped up in those statements. So let's get started by getting a 30,000 foot view of what exactly Stacks is. - -## Stacks Explained in (Slightly Less Than) 10 Minutes - -
- -
+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 @@ -49,19 +34,23 @@ Bitcoin is the most decentralized, most secure, and most immutable blockchain ne 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 "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, Stacks takes a different approach. +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). -By taking this 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. +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. -So Stacks is a Bitcoin layer with some unique properties, like having its own token, that allow it 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. @@ -77,7 +66,7 @@ This is an important property when we are talking about building blockchains tha _Sounds like a sidechain_. -Nope. 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. +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. From 0be224d1a106754b940a7d16a130e5821304180b Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Tue, 14 Feb 2023 21:16:08 +0100 Subject: [PATCH 0908/1444] New translations what-is-stacks.md (Spanish) --- .../current/stacks-academy/what-is-stacks.md | 39 +++++++------------ 1 file changed, 14 insertions(+), 25 deletions(-) diff --git a/i18n/es/docusaurus-plugin-content-docs/current/stacks-academy/what-is-stacks.md b/i18n/es/docusaurus-plugin-content-docs/current/stacks-academy/what-is-stacks.md index 94277da8a9..abada2d864 100644 --- a/i18n/es/docusaurus-plugin-content-docs/current/stacks-academy/what-is-stacks.md +++ b/i18n/es/docusaurus-plugin-content-docs/current/stacks-academy/what-is-stacks.md @@ -10,26 +10,11 @@ We can get an idea of the goal and ethos behind Stacks by looking at [how Satosh > "...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. - -There's a lot of jargon, possible assumptions, controversy, and cool technology wrapped up in those statements. So let's get started by getting a 30,000 foot view of what exactly Stacks is. - -## Stacks Explained in (Slightly Less Than) 10 Minutes - -
- -
+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 @@ -49,19 +34,23 @@ Bitcoin is the most decentralized, most secure, and most immutable blockchain ne 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 "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, Stacks takes a different approach. +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). -By taking this 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. +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. -So Stacks is a Bitcoin layer with some unique properties, like having its own token, that allow it 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. @@ -77,7 +66,7 @@ This is an important property when we are talking about building blockchains tha _Sounds like a sidechain_. -Nope. 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. +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. From 1882c345e51e854a04cafc6db0386bedb5dbcc44 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Tue, 14 Feb 2023 21:16:14 +0100 Subject: [PATCH 0909/1444] New translations what-is-stacks.md (German) --- .../current/stacks-academy/what-is-stacks.md | 39 +++++++------------ 1 file changed, 14 insertions(+), 25 deletions(-) diff --git a/i18n/de/docusaurus-plugin-content-docs/current/stacks-academy/what-is-stacks.md b/i18n/de/docusaurus-plugin-content-docs/current/stacks-academy/what-is-stacks.md index 94277da8a9..abada2d864 100644 --- a/i18n/de/docusaurus-plugin-content-docs/current/stacks-academy/what-is-stacks.md +++ b/i18n/de/docusaurus-plugin-content-docs/current/stacks-academy/what-is-stacks.md @@ -10,26 +10,11 @@ We can get an idea of the goal and ethos behind Stacks by looking at [how Satosh > "...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. - -There's a lot of jargon, possible assumptions, controversy, and cool technology wrapped up in those statements. So let's get started by getting a 30,000 foot view of what exactly Stacks is. - -## Stacks Explained in (Slightly Less Than) 10 Minutes - -
- -
+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 @@ -49,19 +34,23 @@ Bitcoin is the most decentralized, most secure, and most immutable blockchain ne 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 "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, Stacks takes a different approach. +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). -By taking this 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. +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. -So Stacks is a Bitcoin layer with some unique properties, like having its own token, that allow it 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. @@ -77,7 +66,7 @@ This is an important property when we are talking about building blockchains tha _Sounds like a sidechain_. -Nope. 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. +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. From 34a2c6d8fb4b0f54d021f9e392ff5d5b512dbff4 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Tue, 14 Feb 2023 21:16:19 +0100 Subject: [PATCH 0910/1444] New translations what-is-stacks.md (Japanese) --- .../current/stacks-academy/what-is-stacks.md | 39 +++++++------------ 1 file changed, 14 insertions(+), 25 deletions(-) diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/stacks-academy/what-is-stacks.md b/i18n/ja/docusaurus-plugin-content-docs/current/stacks-academy/what-is-stacks.md index 94277da8a9..abada2d864 100644 --- a/i18n/ja/docusaurus-plugin-content-docs/current/stacks-academy/what-is-stacks.md +++ b/i18n/ja/docusaurus-plugin-content-docs/current/stacks-academy/what-is-stacks.md @@ -10,26 +10,11 @@ We can get an idea of the goal and ethos behind Stacks by looking at [how Satosh > "...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. - -There's a lot of jargon, possible assumptions, controversy, and cool technology wrapped up in those statements. So let's get started by getting a 30,000 foot view of what exactly Stacks is. - -## Stacks Explained in (Slightly Less Than) 10 Minutes - -
- -
+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 @@ -49,19 +34,23 @@ Bitcoin is the most decentralized, most secure, and most immutable blockchain ne 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 "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, Stacks takes a different approach. +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). -By taking this 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. +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. -So Stacks is a Bitcoin layer with some unique properties, like having its own token, that allow it 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. @@ -77,7 +66,7 @@ This is an important property when we are talking about building blockchains tha _Sounds like a sidechain_. -Nope. 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. +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. From c782b88e4506eb124e59e670f4a462c8745eb7dc Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Tue, 14 Feb 2023 21:16:25 +0100 Subject: [PATCH 0911/1444] New translations what-is-stacks.md (Korean) --- .../current/stacks-academy/what-is-stacks.md | 39 +++++++------------ 1 file changed, 14 insertions(+), 25 deletions(-) diff --git a/i18n/ko/docusaurus-plugin-content-docs/current/stacks-academy/what-is-stacks.md b/i18n/ko/docusaurus-plugin-content-docs/current/stacks-academy/what-is-stacks.md index 94277da8a9..abada2d864 100644 --- a/i18n/ko/docusaurus-plugin-content-docs/current/stacks-academy/what-is-stacks.md +++ b/i18n/ko/docusaurus-plugin-content-docs/current/stacks-academy/what-is-stacks.md @@ -10,26 +10,11 @@ We can get an idea of the goal and ethos behind Stacks by looking at [how Satosh > "...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. - -There's a lot of jargon, possible assumptions, controversy, and cool technology wrapped up in those statements. So let's get started by getting a 30,000 foot view of what exactly Stacks is. - -## Stacks Explained in (Slightly Less Than) 10 Minutes - -
- -
+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 @@ -49,19 +34,23 @@ Bitcoin is the most decentralized, most secure, and most immutable blockchain ne 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 "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, Stacks takes a different approach. +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). -By taking this 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. +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. -So Stacks is a Bitcoin layer with some unique properties, like having its own token, that allow it 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. @@ -77,7 +66,7 @@ This is an important property when we are talking about building blockchains tha _Sounds like a sidechain_. -Nope. 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. +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. From 516b79aed6a0b64aef28233aa57c10cfdca45577 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Tue, 14 Feb 2023 21:16:30 +0100 Subject: [PATCH 0912/1444] New translations what-is-stacks.md (Russian) --- .../current/stacks-academy/what-is-stacks.md | 39 +++++++------------ 1 file changed, 14 insertions(+), 25 deletions(-) diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/stacks-academy/what-is-stacks.md b/i18n/ru/docusaurus-plugin-content-docs/current/stacks-academy/what-is-stacks.md index 94277da8a9..abada2d864 100644 --- a/i18n/ru/docusaurus-plugin-content-docs/current/stacks-academy/what-is-stacks.md +++ b/i18n/ru/docusaurus-plugin-content-docs/current/stacks-academy/what-is-stacks.md @@ -10,26 +10,11 @@ We can get an idea of the goal and ethos behind Stacks by looking at [how Satosh > "...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. - -There's a lot of jargon, possible assumptions, controversy, and cool technology wrapped up in those statements. So let's get started by getting a 30,000 foot view of what exactly Stacks is. - -## Stacks Explained in (Slightly Less Than) 10 Minutes - -
- -
+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 @@ -49,19 +34,23 @@ Bitcoin is the most decentralized, most secure, and most immutable blockchain ne 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 "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, Stacks takes a different approach. +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). -By taking this 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. +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. -So Stacks is a Bitcoin layer with some unique properties, like having its own token, that allow it 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. @@ -77,7 +66,7 @@ This is an important property when we are talking about building blockchains tha _Sounds like a sidechain_. -Nope. 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. +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. From 1497ed80490272d2d3d022518e4773e6c8573836 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Tue, 14 Feb 2023 21:16:36 +0100 Subject: [PATCH 0913/1444] New translations what-is-stacks.md (Turkish) --- .../current/stacks-academy/what-is-stacks.md | 39 +++++++------------ 1 file changed, 14 insertions(+), 25 deletions(-) diff --git a/i18n/tr/docusaurus-plugin-content-docs/current/stacks-academy/what-is-stacks.md b/i18n/tr/docusaurus-plugin-content-docs/current/stacks-academy/what-is-stacks.md index 94277da8a9..abada2d864 100644 --- a/i18n/tr/docusaurus-plugin-content-docs/current/stacks-academy/what-is-stacks.md +++ b/i18n/tr/docusaurus-plugin-content-docs/current/stacks-academy/what-is-stacks.md @@ -10,26 +10,11 @@ We can get an idea of the goal and ethos behind Stacks by looking at [how Satosh > "...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. - -There's a lot of jargon, possible assumptions, controversy, and cool technology wrapped up in those statements. So let's get started by getting a 30,000 foot view of what exactly Stacks is. - -## Stacks Explained in (Slightly Less Than) 10 Minutes - -
- -
+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 @@ -49,19 +34,23 @@ Bitcoin is the most decentralized, most secure, and most immutable blockchain ne 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 "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, Stacks takes a different approach. +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). -By taking this 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. +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. -So Stacks is a Bitcoin layer with some unique properties, like having its own token, that allow it 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. @@ -77,7 +66,7 @@ This is an important property when we are talking about building blockchains tha _Sounds like a sidechain_. -Nope. 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. +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. From 2fdb3e9b2dec85e7f5e5f7bf678310488c289418 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Tue, 14 Feb 2023 21:16:41 +0100 Subject: [PATCH 0914/1444] New translations what-is-stacks.md (Chinese Simplified) --- .../current/stacks-academy/what-is-stacks.md | 39 +++++++------------ 1 file changed, 14 insertions(+), 25 deletions(-) diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/stacks-academy/what-is-stacks.md b/i18n/zh/docusaurus-plugin-content-docs/current/stacks-academy/what-is-stacks.md index 94277da8a9..abada2d864 100644 --- a/i18n/zh/docusaurus-plugin-content-docs/current/stacks-academy/what-is-stacks.md +++ b/i18n/zh/docusaurus-plugin-content-docs/current/stacks-academy/what-is-stacks.md @@ -10,26 +10,11 @@ We can get an idea of the goal and ethos behind Stacks by looking at [how Satosh > "...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. - -There's a lot of jargon, possible assumptions, controversy, and cool technology wrapped up in those statements. So let's get started by getting a 30,000 foot view of what exactly Stacks is. - -## Stacks Explained in (Slightly Less Than) 10 Minutes - -
- -
+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 @@ -49,19 +34,23 @@ Bitcoin is the most decentralized, most secure, and most immutable blockchain ne 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 "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, Stacks takes a different approach. +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). -By taking this 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. +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. -So Stacks is a Bitcoin layer with some unique properties, like having its own token, that allow it 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. @@ -77,7 +66,7 @@ This is an important property when we are talking about building blockchains tha _Sounds like a sidechain_. -Nope. 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. +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. From dacf1e9b483e816b1ec8cd7ffa09f8d80203dbc4 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Tue, 14 Feb 2023 21:16:47 +0100 Subject: [PATCH 0915/1444] New translations what-is-stacks.md (Vietnamese) --- .../current/stacks-academy/what-is-stacks.md | 39 +++++++------------ 1 file changed, 14 insertions(+), 25 deletions(-) diff --git a/i18n/vi/docusaurus-plugin-content-docs/current/stacks-academy/what-is-stacks.md b/i18n/vi/docusaurus-plugin-content-docs/current/stacks-academy/what-is-stacks.md index 94277da8a9..abada2d864 100644 --- a/i18n/vi/docusaurus-plugin-content-docs/current/stacks-academy/what-is-stacks.md +++ b/i18n/vi/docusaurus-plugin-content-docs/current/stacks-academy/what-is-stacks.md @@ -10,26 +10,11 @@ We can get an idea of the goal and ethos behind Stacks by looking at [how Satosh > "...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. - -There's a lot of jargon, possible assumptions, controversy, and cool technology wrapped up in those statements. So let's get started by getting a 30,000 foot view of what exactly Stacks is. - -## Stacks Explained in (Slightly Less Than) 10 Minutes - -
- -
+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 @@ -49,19 +34,23 @@ Bitcoin is the most decentralized, most secure, and most immutable blockchain ne 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 "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, Stacks takes a different approach. +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). -By taking this 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. +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. -So Stacks is a Bitcoin layer with some unique properties, like having its own token, that allow it 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. @@ -77,7 +66,7 @@ This is an important property when we are talking about building blockchains tha _Sounds like a sidechain_. -Nope. 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. +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. From 9a93b4efd8264b58b0edb6045cd4ac2f087cb1b7 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Tue, 14 Feb 2023 21:16:52 +0100 Subject: [PATCH 0916/1444] New translations what-is-stacks.md (Portuguese, Brazilian) --- .../current/stacks-academy/what-is-stacks.md | 39 +++++++------------ 1 file changed, 14 insertions(+), 25 deletions(-) diff --git a/i18n/pt/docusaurus-plugin-content-docs/current/stacks-academy/what-is-stacks.md b/i18n/pt/docusaurus-plugin-content-docs/current/stacks-academy/what-is-stacks.md index 94277da8a9..abada2d864 100644 --- a/i18n/pt/docusaurus-plugin-content-docs/current/stacks-academy/what-is-stacks.md +++ b/i18n/pt/docusaurus-plugin-content-docs/current/stacks-academy/what-is-stacks.md @@ -10,26 +10,11 @@ We can get an idea of the goal and ethos behind Stacks by looking at [how Satosh > "...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. - -There's a lot of jargon, possible assumptions, controversy, and cool technology wrapped up in those statements. So let's get started by getting a 30,000 foot view of what exactly Stacks is. - -## Stacks Explained in (Slightly Less Than) 10 Minutes - -
- -
+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 @@ -49,19 +34,23 @@ Bitcoin is the most decentralized, most secure, and most immutable blockchain ne 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 "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, Stacks takes a different approach. +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). -By taking this 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. +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. -So Stacks is a Bitcoin layer with some unique properties, like having its own token, that allow it 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. @@ -77,7 +66,7 @@ This is an important property when we are talking about building blockchains tha _Sounds like a sidechain_. -Nope. 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. +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. From 6bd81705bb10f092998d2657080eab550d7b26b1 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Tue, 14 Feb 2023 21:16:58 +0100 Subject: [PATCH 0917/1444] New translations what-is-stacks.md (Indonesian) --- .../current/stacks-academy/what-is-stacks.md | 39 +++++++------------ 1 file changed, 14 insertions(+), 25 deletions(-) diff --git a/i18n/id/docusaurus-plugin-content-docs/current/stacks-academy/what-is-stacks.md b/i18n/id/docusaurus-plugin-content-docs/current/stacks-academy/what-is-stacks.md index 94277da8a9..abada2d864 100644 --- a/i18n/id/docusaurus-plugin-content-docs/current/stacks-academy/what-is-stacks.md +++ b/i18n/id/docusaurus-plugin-content-docs/current/stacks-academy/what-is-stacks.md @@ -10,26 +10,11 @@ We can get an idea of the goal and ethos behind Stacks by looking at [how Satosh > "...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. - -There's a lot of jargon, possible assumptions, controversy, and cool technology wrapped up in those statements. So let's get started by getting a 30,000 foot view of what exactly Stacks is. - -## Stacks Explained in (Slightly Less Than) 10 Minutes - -
- -
+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 @@ -49,19 +34,23 @@ Bitcoin is the most decentralized, most secure, and most immutable blockchain ne 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 "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, Stacks takes a different approach. +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). -By taking this 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. +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. -So Stacks is a Bitcoin layer with some unique properties, like having its own token, that allow it 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. @@ -77,7 +66,7 @@ This is an important property when we are talking about building blockchains tha _Sounds like a sidechain_. -Nope. 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. +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. From ebc9b2fec496524fa4f6b32ab358bb51eb5b5643 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Tue, 14 Feb 2023 21:17:01 +0100 Subject: [PATCH 0918/1444] New translations intro.md (French) --- .../current/intro.md | 56 +++++++++++++++++-- 1 file changed, 51 insertions(+), 5 deletions(-) diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/intro.md b/i18n/fr/docusaurus-plugin-content-docs/current/intro.md index 7d38997514..951a0e5824 100644 --- a/i18n/fr/docusaurus-plugin-content-docs/current/intro.md +++ b/i18n/fr/docusaurus-plugin-content-docs/current/intro.md @@ -1,12 +1,58 @@ --- -sidebar_label: "Home" +sidebar_label: "Start Here" sidebar_position: 1 --- -# Introduction a la Documentation de Stacks +# Stacks Docs -Bienvenue à la documentation officielle de Stacks, apportée par la communautée. +**Stacks is Bitcoin L2 that brings smart contract functionality to Bitcoin, without modifying Bitcoin itself.** -Découvre le minage de Stacks, le jeton STX et le language de programmes Clarity. +These docs serve as: -![](/img/Bitcoinet-L_2.svg) +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. + +## 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) From 5606fdb19825095c5d6e3c0a43041ee064c6679c Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Tue, 14 Feb 2023 21:17:02 +0100 Subject: [PATCH 0919/1444] New translations intro.md (Spanish) --- .../current/intro.md | 56 +++++++++++++++++-- 1 file changed, 51 insertions(+), 5 deletions(-) diff --git a/i18n/es/docusaurus-plugin-content-docs/current/intro.md b/i18n/es/docusaurus-plugin-content-docs/current/intro.md index 8716696a0a..68d02b19ba 100644 --- a/i18n/es/docusaurus-plugin-content-docs/current/intro.md +++ b/i18n/es/docusaurus-plugin-content-docs/current/intro.md @@ -1,12 +1,58 @@ --- -sidebar_label: "Inicio" +sidebar_label: "Start Here" sidebar_position: 1 --- -# Introducción de la documentación de Stacks +# Stacks Docs -Bienvenido a la documentación oficial de Stacks impulsada por la comunidad. +**Stacks is Bitcoin L2 that brings smart contract functionality to Bitcoin, without modifying Bitcoin itself.** -Aprende sobre el minado de Stacks, el token STX y el lenguaje de programación de contratos inteligentes, Clarity. +These docs serve as: -![](/img/Bitcoinet-L_2.svg) +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. + +## 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) + +## Nodos y Mineros + +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) From 26d6fb77daf3be061c4c75cd36546bdd2b73b62d Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Tue, 14 Feb 2023 21:17:03 +0100 Subject: [PATCH 0920/1444] New translations intro.md (German) --- .../current/intro.md | 56 +++++++++++++++++-- 1 file changed, 51 insertions(+), 5 deletions(-) diff --git a/i18n/de/docusaurus-plugin-content-docs/current/intro.md b/i18n/de/docusaurus-plugin-content-docs/current/intro.md index 84f1eaa649..951a0e5824 100644 --- a/i18n/de/docusaurus-plugin-content-docs/current/intro.md +++ b/i18n/de/docusaurus-plugin-content-docs/current/intro.md @@ -1,12 +1,58 @@ --- -sidebar_label: "Home" +sidebar_label: "Start Here" sidebar_position: 1 --- -# Stacks Docs Introduction +# Stacks Docs -Welcome to the community driven official Stacks Documentation. +**Stacks is Bitcoin L2 that brings smart contract functionality to Bitcoin, without modifying Bitcoin itself.** -Learn about Stacks mining, the STX token, and the Clarity smart contract language. +These docs serve as: -![](/img/Bitcoinet-L_2.svg) +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. + +## 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) From 86276aab3802e14dd65a8f2eaa6d06a27cd8aec4 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Tue, 14 Feb 2023 21:17:03 +0100 Subject: [PATCH 0921/1444] New translations intro.md (Japanese) --- .../current/intro.md | 56 +++++++++++++++++-- 1 file changed, 51 insertions(+), 5 deletions(-) diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/intro.md b/i18n/ja/docusaurus-plugin-content-docs/current/intro.md index 84f1eaa649..951a0e5824 100644 --- a/i18n/ja/docusaurus-plugin-content-docs/current/intro.md +++ b/i18n/ja/docusaurus-plugin-content-docs/current/intro.md @@ -1,12 +1,58 @@ --- -sidebar_label: "Home" +sidebar_label: "Start Here" sidebar_position: 1 --- -# Stacks Docs Introduction +# Stacks Docs -Welcome to the community driven official Stacks Documentation. +**Stacks is Bitcoin L2 that brings smart contract functionality to Bitcoin, without modifying Bitcoin itself.** -Learn about Stacks mining, the STX token, and the Clarity smart contract language. +These docs serve as: -![](/img/Bitcoinet-L_2.svg) +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. + +## 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) From f8925e0504dced73e7fd5642117294ccb24e85b6 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Tue, 14 Feb 2023 21:17:08 +0100 Subject: [PATCH 0922/1444] New translations what-is-stacks.md (Hindi) --- .../current/stacks-academy/what-is-stacks.md | 39 +++++++------------ 1 file changed, 14 insertions(+), 25 deletions(-) diff --git a/i18n/hi/docusaurus-plugin-content-docs/current/stacks-academy/what-is-stacks.md b/i18n/hi/docusaurus-plugin-content-docs/current/stacks-academy/what-is-stacks.md index 94277da8a9..abada2d864 100644 --- a/i18n/hi/docusaurus-plugin-content-docs/current/stacks-academy/what-is-stacks.md +++ b/i18n/hi/docusaurus-plugin-content-docs/current/stacks-academy/what-is-stacks.md @@ -10,26 +10,11 @@ We can get an idea of the goal and ethos behind Stacks by looking at [how Satosh > "...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. - -There's a lot of jargon, possible assumptions, controversy, and cool technology wrapped up in those statements. So let's get started by getting a 30,000 foot view of what exactly Stacks is. - -## Stacks Explained in (Slightly Less Than) 10 Minutes - -
- -
+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 @@ -49,19 +34,23 @@ Bitcoin is the most decentralized, most secure, and most immutable blockchain ne 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 "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, Stacks takes a different approach. +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). -By taking this 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. +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. -So Stacks is a Bitcoin layer with some unique properties, like having its own token, that allow it 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. @@ -77,7 +66,7 @@ This is an important property when we are talking about building blockchains tha _Sounds like a sidechain_. -Nope. 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. +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. From e78a578288d126ffcca1e94948b613ba87efa821 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Tue, 14 Feb 2023 21:17:11 +0100 Subject: [PATCH 0923/1444] New translations intro.md (Korean) --- .../current/intro.md | 56 +++++++++++++++++-- 1 file changed, 51 insertions(+), 5 deletions(-) diff --git a/i18n/ko/docusaurus-plugin-content-docs/current/intro.md b/i18n/ko/docusaurus-plugin-content-docs/current/intro.md index 84f1eaa649..951a0e5824 100644 --- a/i18n/ko/docusaurus-plugin-content-docs/current/intro.md +++ b/i18n/ko/docusaurus-plugin-content-docs/current/intro.md @@ -1,12 +1,58 @@ --- -sidebar_label: "Home" +sidebar_label: "Start Here" sidebar_position: 1 --- -# Stacks Docs Introduction +# Stacks Docs -Welcome to the community driven official Stacks Documentation. +**Stacks is Bitcoin L2 that brings smart contract functionality to Bitcoin, without modifying Bitcoin itself.** -Learn about Stacks mining, the STX token, and the Clarity smart contract language. +These docs serve as: -![](/img/Bitcoinet-L_2.svg) +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. + +## 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) From f37f1386f4178099bd19d3c4d45affb557f91f9f Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Tue, 14 Feb 2023 21:17:12 +0100 Subject: [PATCH 0924/1444] New translations intro.md (Russian) --- .../current/intro.md | 56 +++++++++++++++++-- 1 file changed, 51 insertions(+), 5 deletions(-) diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/intro.md b/i18n/ru/docusaurus-plugin-content-docs/current/intro.md index 84f1eaa649..951a0e5824 100644 --- a/i18n/ru/docusaurus-plugin-content-docs/current/intro.md +++ b/i18n/ru/docusaurus-plugin-content-docs/current/intro.md @@ -1,12 +1,58 @@ --- -sidebar_label: "Home" +sidebar_label: "Start Here" sidebar_position: 1 --- -# Stacks Docs Introduction +# Stacks Docs -Welcome to the community driven official Stacks Documentation. +**Stacks is Bitcoin L2 that brings smart contract functionality to Bitcoin, without modifying Bitcoin itself.** -Learn about Stacks mining, the STX token, and the Clarity smart contract language. +These docs serve as: -![](/img/Bitcoinet-L_2.svg) +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. + +## 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) From a8a86de61be08d92f5acb5d2c25fb7a1069b1769 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Tue, 14 Feb 2023 21:17:13 +0100 Subject: [PATCH 0925/1444] New translations intro.md (Turkish) --- .../current/intro.md | 56 +++++++++++++++++-- 1 file changed, 51 insertions(+), 5 deletions(-) diff --git a/i18n/tr/docusaurus-plugin-content-docs/current/intro.md b/i18n/tr/docusaurus-plugin-content-docs/current/intro.md index ea521dd1f5..951a0e5824 100644 --- a/i18n/tr/docusaurus-plugin-content-docs/current/intro.md +++ b/i18n/tr/docusaurus-plugin-content-docs/current/intro.md @@ -1,12 +1,58 @@ --- -sidebar_label: "Ana sayfa" +sidebar_label: "Start Here" sidebar_position: 1 --- -# Stacks Dokümanları Tanıtımı +# Stacks Docs -Topluluk odaklı resmi Stacks Dokümantasyonuna hoş geldiniz. +**Stacks is Bitcoin L2 that brings smart contract functionality to Bitcoin, without modifying Bitcoin itself.** -Stacks madenciliği, STX token ve Clarity akıllı sözleşme dili hakkında bilgi edinin. +These docs serve as: -![](/img/Bitcoinet-L_2.svg) +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. + +## 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) From 8b94acd9f42fd6a41d4f61090893963ab772c5bb Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Tue, 14 Feb 2023 21:17:14 +0100 Subject: [PATCH 0926/1444] New translations intro.md (Chinese Simplified) --- .../current/intro.md | 56 +++++++++++++++++-- 1 file changed, 51 insertions(+), 5 deletions(-) diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/intro.md b/i18n/zh/docusaurus-plugin-content-docs/current/intro.md index 84f1eaa649..951a0e5824 100644 --- a/i18n/zh/docusaurus-plugin-content-docs/current/intro.md +++ b/i18n/zh/docusaurus-plugin-content-docs/current/intro.md @@ -1,12 +1,58 @@ --- -sidebar_label: "Home" +sidebar_label: "Start Here" sidebar_position: 1 --- -# Stacks Docs Introduction +# Stacks Docs -Welcome to the community driven official Stacks Documentation. +**Stacks is Bitcoin L2 that brings smart contract functionality to Bitcoin, without modifying Bitcoin itself.** -Learn about Stacks mining, the STX token, and the Clarity smart contract language. +These docs serve as: -![](/img/Bitcoinet-L_2.svg) +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. + +## 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) From fd8ccfee304e11d2759d3fdfc8e5f456c57f9c27 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Tue, 14 Feb 2023 21:17:15 +0100 Subject: [PATCH 0927/1444] New translations intro.md (Vietnamese) --- .../current/intro.md | 56 +++++++++++++++++-- 1 file changed, 51 insertions(+), 5 deletions(-) diff --git a/i18n/vi/docusaurus-plugin-content-docs/current/intro.md b/i18n/vi/docusaurus-plugin-content-docs/current/intro.md index 84f1eaa649..951a0e5824 100644 --- a/i18n/vi/docusaurus-plugin-content-docs/current/intro.md +++ b/i18n/vi/docusaurus-plugin-content-docs/current/intro.md @@ -1,12 +1,58 @@ --- -sidebar_label: "Home" +sidebar_label: "Start Here" sidebar_position: 1 --- -# Stacks Docs Introduction +# Stacks Docs -Welcome to the community driven official Stacks Documentation. +**Stacks is Bitcoin L2 that brings smart contract functionality to Bitcoin, without modifying Bitcoin itself.** -Learn about Stacks mining, the STX token, and the Clarity smart contract language. +These docs serve as: -![](/img/Bitcoinet-L_2.svg) +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. + +## 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) From 04d59d1de0625914ca3bb813ac6488f1f1710c14 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Tue, 14 Feb 2023 21:17:15 +0100 Subject: [PATCH 0928/1444] New translations intro.md (Portuguese, Brazilian) --- .../current/intro.md | 56 +++++++++++++++++-- 1 file changed, 51 insertions(+), 5 deletions(-) diff --git a/i18n/pt/docusaurus-plugin-content-docs/current/intro.md b/i18n/pt/docusaurus-plugin-content-docs/current/intro.md index 84f1eaa649..951a0e5824 100644 --- a/i18n/pt/docusaurus-plugin-content-docs/current/intro.md +++ b/i18n/pt/docusaurus-plugin-content-docs/current/intro.md @@ -1,12 +1,58 @@ --- -sidebar_label: "Home" +sidebar_label: "Start Here" sidebar_position: 1 --- -# Stacks Docs Introduction +# Stacks Docs -Welcome to the community driven official Stacks Documentation. +**Stacks is Bitcoin L2 that brings smart contract functionality to Bitcoin, without modifying Bitcoin itself.** -Learn about Stacks mining, the STX token, and the Clarity smart contract language. +These docs serve as: -![](/img/Bitcoinet-L_2.svg) +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. + +## 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) From f7627c8a6ae16e480f150faf8a56be653ecd325f Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Tue, 14 Feb 2023 21:17:16 +0100 Subject: [PATCH 0929/1444] New translations intro.md (Indonesian) --- .../current/intro.md | 56 +++++++++++++++++-- 1 file changed, 51 insertions(+), 5 deletions(-) diff --git a/i18n/id/docusaurus-plugin-content-docs/current/intro.md b/i18n/id/docusaurus-plugin-content-docs/current/intro.md index 404fb77266..34767dc88a 100644 --- a/i18n/id/docusaurus-plugin-content-docs/current/intro.md +++ b/i18n/id/docusaurus-plugin-content-docs/current/intro.md @@ -1,12 +1,58 @@ --- -sidebar_label: "Beranda" +sidebar_label: "Start Here" sidebar_position: 1 --- -# Stacks Pendahuluan +# Stacks Docs -Selamat datang di Dokumentasi Stacks resmi yang digerakkan oleh komunitas. +**Stacks is Bitcoin L2 that brings smart contract functionality to Bitcoin, without modifying Bitcoin itself.** -Belajar tentang penambangan Stacks, token STX, dan bahasa pemrograman kontrak pintar Clarity. +These docs serve as: -![](/img/Bitcoinet-L_2.svg) +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. + +## 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) + +## Noda dan Penambang + +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) From 4eb501136ef822dfcc20a0213834b79d30e78f0f Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Tue, 14 Feb 2023 21:17:17 +0100 Subject: [PATCH 0930/1444] New translations intro.md (Hindi) --- .../current/intro.md | 56 +++++++++++++++++-- 1 file changed, 51 insertions(+), 5 deletions(-) diff --git a/i18n/hi/docusaurus-plugin-content-docs/current/intro.md b/i18n/hi/docusaurus-plugin-content-docs/current/intro.md index 84f1eaa649..951a0e5824 100644 --- a/i18n/hi/docusaurus-plugin-content-docs/current/intro.md +++ b/i18n/hi/docusaurus-plugin-content-docs/current/intro.md @@ -1,12 +1,58 @@ --- -sidebar_label: "Home" +sidebar_label: "Start Here" sidebar_position: 1 --- -# Stacks Docs Introduction +# Stacks Docs -Welcome to the community driven official Stacks Documentation. +**Stacks is Bitcoin L2 that brings smart contract functionality to Bitcoin, without modifying Bitcoin itself.** -Learn about Stacks mining, the STX token, and the Clarity smart contract language. +These docs serve as: -![](/img/Bitcoinet-L_2.svg) +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. + +## 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) From 86d8400a798ad9d68957fb5afdc18ef6700447a1 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Fri, 24 Feb 2023 21:19:15 +0100 Subject: [PATCH 0931/1444] Update source file intro.md --- docs/intro.md | 56 ++++++++++++++++++++++++++++++++++++++++++++++----- 1 file changed, 51 insertions(+), 5 deletions(-) diff --git a/docs/intro.md b/docs/intro.md index 84f1eaa649..951a0e5824 100644 --- a/docs/intro.md +++ b/docs/intro.md @@ -1,12 +1,58 @@ --- -sidebar_label: "Home" +sidebar_label: "Start Here" sidebar_position: 1 --- -# Stacks Docs Introduction +# Stacks Docs -Welcome to the community driven official Stacks Documentation. +**Stacks is Bitcoin L2 that brings smart contract functionality to Bitcoin, without modifying Bitcoin itself.** -Learn about Stacks mining, the STX token, and the Clarity smart contract language. +These docs serve as: -![](/img/Bitcoinet-L_2.svg) +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. + +## 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) From dc8c4148862df5a37d782d6227d0685406502392 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Fri, 24 Feb 2023 21:19:23 +0100 Subject: [PATCH 0932/1444] Update source file what-is-stacks.md --- docs/stacks-academy/what-is-stacks.md | 41 +++++++++------------------ 1 file changed, 14 insertions(+), 27 deletions(-) diff --git a/docs/stacks-academy/what-is-stacks.md b/docs/stacks-academy/what-is-stacks.md index 0e3210b364..abada2d864 100644 --- a/docs/stacks-academy/what-is-stacks.md +++ b/docs/stacks-academy/what-is-stacks.md @@ -10,28 +10,11 @@ We can get an idea of the goal and ethos behind Stacks by looking at [how Satosh > "...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. - -There's a lot of jargon, possible assumptions, controversy, and cool technology wrapped up in those statements. So let's get started by getting a 30,000 foot view of what exactly Stacks is. - -## Stacks Explained in (Slightly Less Than) 10 Minutes - -
- -
+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 @@ -51,19 +34,23 @@ Bitcoin is the most decentralized, most secure, and most immutable blockchain ne 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 "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, Stacks takes a different approach. +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). -By taking this 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. +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. -So Stacks is a Bitcoin layer with some unique properties, like having its own token, that allow it 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. @@ -79,7 +66,7 @@ This is an important property when we are talking about building blockchains tha _Sounds like a sidechain_. -Nope. 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. +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. From b94d1f10909a2e9657dc9568d33c293f985fb1b9 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Tue, 28 Feb 2023 19:51:45 +0100 Subject: [PATCH 0933/1444] New translations crash-course.md (French) --- .../current/clarity/crash-course.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/clarity/crash-course.md b/i18n/fr/docusaurus-plugin-content-docs/current/clarity/crash-course.md index 5b27a3c275..836fe1b158 100644 --- a/i18n/fr/docusaurus-plugin-content-docs/current/clarity/crash-course.md +++ b/i18n/fr/docusaurus-plugin-content-docs/current/clarity/crash-course.md @@ -38,7 +38,7 @@ Clarity takes inspiration from LISP, and you can think of everything in Clarity 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.md). +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. @@ -50,7 +50,7 @@ Why am I describing this as if we are calling a function? Because we are, and it Let's expand on this concept a bit by deleting this and writing a new function. -```clojure +```clarity (define-data-var count int 0) (define-public (add-number (number int)) (let @@ -101,7 +101,7 @@ So this `let` function is a way of wrapping a multi-step function into a single But it does one other crucial thing at the beginning. This line: -```clojure +```clarity (current-count count) ``` From 42c8961a441f5c4762c02711b22a590b8cb50c3d Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Tue, 28 Feb 2023 19:51:52 +0100 Subject: [PATCH 0934/1444] New translations _category_.json (French) --- .../clarity/noteworthy-contracts/_category_.json | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/_category_.json b/i18n/fr/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/_category_.json index f5de305558..14b9388b4d 100644 --- a/i18n/fr/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/_category_.json +++ b/i18n/fr/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/_category_.json @@ -1,8 +1,8 @@ { - "label": "Noteworthy Contracts", - "position": 4, - "link": { - "type": "generated-index", - "description": "Specific deployed Clarity Contracts worth mentioning." - } -} \ No newline at end of file + "label": "Noteworthy Contracts", + "position": 4, + "link": { + "type": "generated-index", + "description": "Specific deployed Clarity Contracts worth mentioning." + } +} From 22e2cefc29b0a4fd738b8b6e25687ee14a0d3259 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Tue, 28 Feb 2023 19:52:39 +0100 Subject: [PATCH 0935/1444] New translations crash-course.md (Spanish) --- .../current/clarity/crash-course.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/i18n/es/docusaurus-plugin-content-docs/current/clarity/crash-course.md b/i18n/es/docusaurus-plugin-content-docs/current/clarity/crash-course.md index 5b27a3c275..836fe1b158 100644 --- a/i18n/es/docusaurus-plugin-content-docs/current/clarity/crash-course.md +++ b/i18n/es/docusaurus-plugin-content-docs/current/clarity/crash-course.md @@ -38,7 +38,7 @@ Clarity takes inspiration from LISP, and you can think of everything in Clarity 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.md). +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. @@ -50,7 +50,7 @@ Why am I describing this as if we are calling a function? Because we are, and it Let's expand on this concept a bit by deleting this and writing a new function. -```clojure +```clarity (define-data-var count int 0) (define-public (add-number (number int)) (let @@ -101,7 +101,7 @@ So this `let` function is a way of wrapping a multi-step function into a single But it does one other crucial thing at the beginning. This line: -```clojure +```clarity (current-count count) ``` From 8b9e6857784367b18f946a8ac43967bcb6ccf84c Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Tue, 28 Feb 2023 19:52:46 +0100 Subject: [PATCH 0936/1444] New translations _category_.json (Spanish) --- .../clarity/noteworthy-contracts/_category_.json | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/i18n/es/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/_category_.json b/i18n/es/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/_category_.json index f5de305558..14b9388b4d 100644 --- a/i18n/es/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/_category_.json +++ b/i18n/es/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/_category_.json @@ -1,8 +1,8 @@ { - "label": "Noteworthy Contracts", - "position": 4, - "link": { - "type": "generated-index", - "description": "Specific deployed Clarity Contracts worth mentioning." - } -} \ No newline at end of file + "label": "Noteworthy Contracts", + "position": 4, + "link": { + "type": "generated-index", + "description": "Specific deployed Clarity Contracts worth mentioning." + } +} From b4f07868b1917e6db348f6dc237fecb9a8296e1a Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Tue, 28 Feb 2023 19:53:17 +0100 Subject: [PATCH 0937/1444] New translations crash-course.md (German) --- .../current/clarity/crash-course.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/i18n/de/docusaurus-plugin-content-docs/current/clarity/crash-course.md b/i18n/de/docusaurus-plugin-content-docs/current/clarity/crash-course.md index 5b27a3c275..836fe1b158 100644 --- a/i18n/de/docusaurus-plugin-content-docs/current/clarity/crash-course.md +++ b/i18n/de/docusaurus-plugin-content-docs/current/clarity/crash-course.md @@ -38,7 +38,7 @@ Clarity takes inspiration from LISP, and you can think of everything in Clarity 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.md). +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. @@ -50,7 +50,7 @@ Why am I describing this as if we are calling a function? Because we are, and it Let's expand on this concept a bit by deleting this and writing a new function. -```clojure +```clarity (define-data-var count int 0) (define-public (add-number (number int)) (let @@ -101,7 +101,7 @@ So this `let` function is a way of wrapping a multi-step function into a single But it does one other crucial thing at the beginning. This line: -```clojure +```clarity (current-count count) ``` From cd43dd8d80efbc163f7084a692b54d865682beed Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Tue, 28 Feb 2023 19:53:23 +0100 Subject: [PATCH 0938/1444] New translations _category_.json (German) --- .../clarity/noteworthy-contracts/_category_.json | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/i18n/de/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/_category_.json b/i18n/de/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/_category_.json index f5de305558..14b9388b4d 100644 --- a/i18n/de/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/_category_.json +++ b/i18n/de/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/_category_.json @@ -1,8 +1,8 @@ { - "label": "Noteworthy Contracts", - "position": 4, - "link": { - "type": "generated-index", - "description": "Specific deployed Clarity Contracts worth mentioning." - } -} \ No newline at end of file + "label": "Noteworthy Contracts", + "position": 4, + "link": { + "type": "generated-index", + "description": "Specific deployed Clarity Contracts worth mentioning." + } +} From 30567c4c420306dfab40d3fefd858050cf742aca Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Tue, 28 Feb 2023 19:53:55 +0100 Subject: [PATCH 0939/1444] New translations crash-course.md (Japanese) --- .../current/clarity/crash-course.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/clarity/crash-course.md b/i18n/ja/docusaurus-plugin-content-docs/current/clarity/crash-course.md index 5b27a3c275..836fe1b158 100644 --- a/i18n/ja/docusaurus-plugin-content-docs/current/clarity/crash-course.md +++ b/i18n/ja/docusaurus-plugin-content-docs/current/clarity/crash-course.md @@ -38,7 +38,7 @@ Clarity takes inspiration from LISP, and you can think of everything in Clarity 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.md). +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. @@ -50,7 +50,7 @@ Why am I describing this as if we are calling a function? Because we are, and it Let's expand on this concept a bit by deleting this and writing a new function. -```clojure +```clarity (define-data-var count int 0) (define-public (add-number (number int)) (let @@ -101,7 +101,7 @@ So this `let` function is a way of wrapping a multi-step function into a single But it does one other crucial thing at the beginning. This line: -```clojure +```clarity (current-count count) ``` From 59208f90de2d35250c8fdf6401d46da5bbc54cd2 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Tue, 28 Feb 2023 19:54:01 +0100 Subject: [PATCH 0940/1444] New translations _category_.json (Japanese) --- .../clarity/noteworthy-contracts/_category_.json | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/_category_.json b/i18n/ja/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/_category_.json index f5de305558..14b9388b4d 100644 --- a/i18n/ja/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/_category_.json +++ b/i18n/ja/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/_category_.json @@ -1,8 +1,8 @@ { - "label": "Noteworthy Contracts", - "position": 4, - "link": { - "type": "generated-index", - "description": "Specific deployed Clarity Contracts worth mentioning." - } -} \ No newline at end of file + "label": "Noteworthy Contracts", + "position": 4, + "link": { + "type": "generated-index", + "description": "Specific deployed Clarity Contracts worth mentioning." + } +} From 8a31df57eaa390e3afb8c08b10af549961c13df4 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Tue, 28 Feb 2023 19:54:32 +0100 Subject: [PATCH 0941/1444] New translations crash-course.md (Korean) --- .../current/clarity/crash-course.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/i18n/ko/docusaurus-plugin-content-docs/current/clarity/crash-course.md b/i18n/ko/docusaurus-plugin-content-docs/current/clarity/crash-course.md index 5b27a3c275..836fe1b158 100644 --- a/i18n/ko/docusaurus-plugin-content-docs/current/clarity/crash-course.md +++ b/i18n/ko/docusaurus-plugin-content-docs/current/clarity/crash-course.md @@ -38,7 +38,7 @@ Clarity takes inspiration from LISP, and you can think of everything in Clarity 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.md). +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. @@ -50,7 +50,7 @@ Why am I describing this as if we are calling a function? Because we are, and it Let's expand on this concept a bit by deleting this and writing a new function. -```clojure +```clarity (define-data-var count int 0) (define-public (add-number (number int)) (let @@ -101,7 +101,7 @@ So this `let` function is a way of wrapping a multi-step function into a single But it does one other crucial thing at the beginning. This line: -```clojure +```clarity (current-count count) ``` From 73b5f31004d647e94081303d567f4b9cdc76a856 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Tue, 28 Feb 2023 19:54:38 +0100 Subject: [PATCH 0942/1444] New translations _category_.json (Korean) --- .../clarity/noteworthy-contracts/_category_.json | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/i18n/ko/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/_category_.json b/i18n/ko/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/_category_.json index f5de305558..14b9388b4d 100644 --- a/i18n/ko/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/_category_.json +++ b/i18n/ko/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/_category_.json @@ -1,8 +1,8 @@ { - "label": "Noteworthy Contracts", - "position": 4, - "link": { - "type": "generated-index", - "description": "Specific deployed Clarity Contracts worth mentioning." - } -} \ No newline at end of file + "label": "Noteworthy Contracts", + "position": 4, + "link": { + "type": "generated-index", + "description": "Specific deployed Clarity Contracts worth mentioning." + } +} From 7122271f4b665ecb548922b7bc2007c5227e3631 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Tue, 28 Feb 2023 19:55:09 +0100 Subject: [PATCH 0943/1444] New translations crash-course.md (Russian) --- .../current/clarity/crash-course.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/clarity/crash-course.md b/i18n/ru/docusaurus-plugin-content-docs/current/clarity/crash-course.md index 5b27a3c275..836fe1b158 100644 --- a/i18n/ru/docusaurus-plugin-content-docs/current/clarity/crash-course.md +++ b/i18n/ru/docusaurus-plugin-content-docs/current/clarity/crash-course.md @@ -38,7 +38,7 @@ Clarity takes inspiration from LISP, and you can think of everything in Clarity 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.md). +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. @@ -50,7 +50,7 @@ Why am I describing this as if we are calling a function? Because we are, and it Let's expand on this concept a bit by deleting this and writing a new function. -```clojure +```clarity (define-data-var count int 0) (define-public (add-number (number int)) (let @@ -101,7 +101,7 @@ So this `let` function is a way of wrapping a multi-step function into a single But it does one other crucial thing at the beginning. This line: -```clojure +```clarity (current-count count) ``` From 0ec360e823bc968388e999256d971027af905df5 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Tue, 28 Feb 2023 19:55:15 +0100 Subject: [PATCH 0944/1444] New translations _category_.json (Russian) --- .../clarity/noteworthy-contracts/_category_.json | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/_category_.json b/i18n/ru/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/_category_.json index f5de305558..14b9388b4d 100644 --- a/i18n/ru/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/_category_.json +++ b/i18n/ru/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/_category_.json @@ -1,8 +1,8 @@ { - "label": "Noteworthy Contracts", - "position": 4, - "link": { - "type": "generated-index", - "description": "Specific deployed Clarity Contracts worth mentioning." - } -} \ No newline at end of file + "label": "Noteworthy Contracts", + "position": 4, + "link": { + "type": "generated-index", + "description": "Specific deployed Clarity Contracts worth mentioning." + } +} From 11582dca3fe33ba0eac89e7172feb5e53b9044d0 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Tue, 28 Feb 2023 19:55:46 +0100 Subject: [PATCH 0945/1444] New translations crash-course.md (Turkish) --- .../current/clarity/crash-course.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/i18n/tr/docusaurus-plugin-content-docs/current/clarity/crash-course.md b/i18n/tr/docusaurus-plugin-content-docs/current/clarity/crash-course.md index 5b27a3c275..836fe1b158 100644 --- a/i18n/tr/docusaurus-plugin-content-docs/current/clarity/crash-course.md +++ b/i18n/tr/docusaurus-plugin-content-docs/current/clarity/crash-course.md @@ -38,7 +38,7 @@ Clarity takes inspiration from LISP, and you can think of everything in Clarity 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.md). +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. @@ -50,7 +50,7 @@ Why am I describing this as if we are calling a function? Because we are, and it Let's expand on this concept a bit by deleting this and writing a new function. -```clojure +```clarity (define-data-var count int 0) (define-public (add-number (number int)) (let @@ -101,7 +101,7 @@ So this `let` function is a way of wrapping a multi-step function into a single But it does one other crucial thing at the beginning. This line: -```clojure +```clarity (current-count count) ``` From 9b79acd3e7a9708d978df56117e3c4f721de7f28 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Tue, 28 Feb 2023 19:55:52 +0100 Subject: [PATCH 0946/1444] New translations _category_.json (Turkish) --- .../clarity/noteworthy-contracts/_category_.json | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/i18n/tr/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/_category_.json b/i18n/tr/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/_category_.json index f5de305558..14b9388b4d 100644 --- a/i18n/tr/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/_category_.json +++ b/i18n/tr/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/_category_.json @@ -1,8 +1,8 @@ { - "label": "Noteworthy Contracts", - "position": 4, - "link": { - "type": "generated-index", - "description": "Specific deployed Clarity Contracts worth mentioning." - } -} \ No newline at end of file + "label": "Noteworthy Contracts", + "position": 4, + "link": { + "type": "generated-index", + "description": "Specific deployed Clarity Contracts worth mentioning." + } +} From c40b36b638c34d825f4727acfcfd2f6d9ad53aac Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Tue, 28 Feb 2023 19:56:24 +0100 Subject: [PATCH 0947/1444] New translations crash-course.md (Chinese Simplified) --- .../current/clarity/crash-course.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/clarity/crash-course.md b/i18n/zh/docusaurus-plugin-content-docs/current/clarity/crash-course.md index 5b27a3c275..836fe1b158 100644 --- a/i18n/zh/docusaurus-plugin-content-docs/current/clarity/crash-course.md +++ b/i18n/zh/docusaurus-plugin-content-docs/current/clarity/crash-course.md @@ -38,7 +38,7 @@ Clarity takes inspiration from LISP, and you can think of everything in Clarity 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.md). +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. @@ -50,7 +50,7 @@ Why am I describing this as if we are calling a function? Because we are, and it Let's expand on this concept a bit by deleting this and writing a new function. -```clojure +```clarity (define-data-var count int 0) (define-public (add-number (number int)) (let @@ -101,7 +101,7 @@ So this `let` function is a way of wrapping a multi-step function into a single But it does one other crucial thing at the beginning. This line: -```clojure +```clarity (current-count count) ``` From 2baf080abfa7d2ac5afa5b95029ea0c8c94e84c4 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Tue, 28 Feb 2023 19:56:30 +0100 Subject: [PATCH 0948/1444] New translations _category_.json (Chinese Simplified) --- .../clarity/noteworthy-contracts/_category_.json | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/_category_.json b/i18n/zh/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/_category_.json index f5de305558..14b9388b4d 100644 --- a/i18n/zh/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/_category_.json +++ b/i18n/zh/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/_category_.json @@ -1,8 +1,8 @@ { - "label": "Noteworthy Contracts", - "position": 4, - "link": { - "type": "generated-index", - "description": "Specific deployed Clarity Contracts worth mentioning." - } -} \ No newline at end of file + "label": "Noteworthy Contracts", + "position": 4, + "link": { + "type": "generated-index", + "description": "Specific deployed Clarity Contracts worth mentioning." + } +} From e57e9b2fe546f399919e08d312335c94383f1dfd Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Tue, 28 Feb 2023 19:57:01 +0100 Subject: [PATCH 0949/1444] New translations crash-course.md (Vietnamese) --- .../current/clarity/crash-course.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/i18n/vi/docusaurus-plugin-content-docs/current/clarity/crash-course.md b/i18n/vi/docusaurus-plugin-content-docs/current/clarity/crash-course.md index 5b27a3c275..836fe1b158 100644 --- a/i18n/vi/docusaurus-plugin-content-docs/current/clarity/crash-course.md +++ b/i18n/vi/docusaurus-plugin-content-docs/current/clarity/crash-course.md @@ -38,7 +38,7 @@ Clarity takes inspiration from LISP, and you can think of everything in Clarity 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.md). +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. @@ -50,7 +50,7 @@ Why am I describing this as if we are calling a function? Because we are, and it Let's expand on this concept a bit by deleting this and writing a new function. -```clojure +```clarity (define-data-var count int 0) (define-public (add-number (number int)) (let @@ -101,7 +101,7 @@ So this `let` function is a way of wrapping a multi-step function into a single But it does one other crucial thing at the beginning. This line: -```clojure +```clarity (current-count count) ``` From a47a32c4524d2d4a30eaa208181b47f36b91a0ae Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Tue, 28 Feb 2023 19:57:07 +0100 Subject: [PATCH 0950/1444] New translations _category_.json (Vietnamese) --- .../clarity/noteworthy-contracts/_category_.json | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/i18n/vi/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/_category_.json b/i18n/vi/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/_category_.json index f5de305558..14b9388b4d 100644 --- a/i18n/vi/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/_category_.json +++ b/i18n/vi/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/_category_.json @@ -1,8 +1,8 @@ { - "label": "Noteworthy Contracts", - "position": 4, - "link": { - "type": "generated-index", - "description": "Specific deployed Clarity Contracts worth mentioning." - } -} \ No newline at end of file + "label": "Noteworthy Contracts", + "position": 4, + "link": { + "type": "generated-index", + "description": "Specific deployed Clarity Contracts worth mentioning." + } +} From 1a85030b636beafadf28fea58cfbd41714fd63ea Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Tue, 28 Feb 2023 19:57:37 +0100 Subject: [PATCH 0951/1444] New translations crash-course.md (Portuguese, Brazilian) --- .../current/clarity/crash-course.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/i18n/pt/docusaurus-plugin-content-docs/current/clarity/crash-course.md b/i18n/pt/docusaurus-plugin-content-docs/current/clarity/crash-course.md index 5b27a3c275..836fe1b158 100644 --- a/i18n/pt/docusaurus-plugin-content-docs/current/clarity/crash-course.md +++ b/i18n/pt/docusaurus-plugin-content-docs/current/clarity/crash-course.md @@ -38,7 +38,7 @@ Clarity takes inspiration from LISP, and you can think of everything in Clarity 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.md). +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. @@ -50,7 +50,7 @@ Why am I describing this as if we are calling a function? Because we are, and it Let's expand on this concept a bit by deleting this and writing a new function. -```clojure +```clarity (define-data-var count int 0) (define-public (add-number (number int)) (let @@ -101,7 +101,7 @@ So this `let` function is a way of wrapping a multi-step function into a single But it does one other crucial thing at the beginning. This line: -```clojure +```clarity (current-count count) ``` From 399223933a79867ae5af5f69adc673a8d0226403 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Tue, 28 Feb 2023 19:57:43 +0100 Subject: [PATCH 0952/1444] New translations _category_.json (Portuguese, Brazilian) --- .../clarity/noteworthy-contracts/_category_.json | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/i18n/pt/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/_category_.json b/i18n/pt/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/_category_.json index f5de305558..14b9388b4d 100644 --- a/i18n/pt/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/_category_.json +++ b/i18n/pt/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/_category_.json @@ -1,8 +1,8 @@ { - "label": "Noteworthy Contracts", - "position": 4, - "link": { - "type": "generated-index", - "description": "Specific deployed Clarity Contracts worth mentioning." - } -} \ No newline at end of file + "label": "Noteworthy Contracts", + "position": 4, + "link": { + "type": "generated-index", + "description": "Specific deployed Clarity Contracts worth mentioning." + } +} From 2fcc87da72c522db4f8f652508bfd92f9e82354e Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Tue, 28 Feb 2023 19:58:13 +0100 Subject: [PATCH 0953/1444] New translations crash-course.md (Indonesian) --- .../current/clarity/crash-course.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/i18n/id/docusaurus-plugin-content-docs/current/clarity/crash-course.md b/i18n/id/docusaurus-plugin-content-docs/current/clarity/crash-course.md index 5b27a3c275..836fe1b158 100644 --- a/i18n/id/docusaurus-plugin-content-docs/current/clarity/crash-course.md +++ b/i18n/id/docusaurus-plugin-content-docs/current/clarity/crash-course.md @@ -38,7 +38,7 @@ Clarity takes inspiration from LISP, and you can think of everything in Clarity 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.md). +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. @@ -50,7 +50,7 @@ Why am I describing this as if we are calling a function? Because we are, and it Let's expand on this concept a bit by deleting this and writing a new function. -```clojure +```clarity (define-data-var count int 0) (define-public (add-number (number int)) (let @@ -101,7 +101,7 @@ So this `let` function is a way of wrapping a multi-step function into a single But it does one other crucial thing at the beginning. This line: -```clojure +```clarity (current-count count) ``` From cf0bdd09476a16a068a04ecad6f4e072eab5c45c Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Tue, 28 Feb 2023 19:58:19 +0100 Subject: [PATCH 0954/1444] New translations _category_.json (Indonesian) --- .../clarity/noteworthy-contracts/_category_.json | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/i18n/id/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/_category_.json b/i18n/id/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/_category_.json index f5de305558..14b9388b4d 100644 --- a/i18n/id/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/_category_.json +++ b/i18n/id/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/_category_.json @@ -1,8 +1,8 @@ { - "label": "Noteworthy Contracts", - "position": 4, - "link": { - "type": "generated-index", - "description": "Specific deployed Clarity Contracts worth mentioning." - } -} \ No newline at end of file + "label": "Noteworthy Contracts", + "position": 4, + "link": { + "type": "generated-index", + "description": "Specific deployed Clarity Contracts worth mentioning." + } +} From 7e22082a9f9c83b4df24839ca892183efcc8de90 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Tue, 28 Feb 2023 19:58:50 +0100 Subject: [PATCH 0955/1444] New translations crash-course.md (Hindi) --- .../current/clarity/crash-course.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/i18n/hi/docusaurus-plugin-content-docs/current/clarity/crash-course.md b/i18n/hi/docusaurus-plugin-content-docs/current/clarity/crash-course.md index 5b27a3c275..836fe1b158 100644 --- a/i18n/hi/docusaurus-plugin-content-docs/current/clarity/crash-course.md +++ b/i18n/hi/docusaurus-plugin-content-docs/current/clarity/crash-course.md @@ -38,7 +38,7 @@ Clarity takes inspiration from LISP, and you can think of everything in Clarity 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.md). +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. @@ -50,7 +50,7 @@ Why am I describing this as if we are calling a function? Because we are, and it Let's expand on this concept a bit by deleting this and writing a new function. -```clojure +```clarity (define-data-var count int 0) (define-public (add-number (number int)) (let @@ -101,7 +101,7 @@ So this `let` function is a way of wrapping a multi-step function into a single But it does one other crucial thing at the beginning. This line: -```clojure +```clarity (current-count count) ``` From 246515910304c18aa954dd6d970e1b8fcdf7ec1a Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Tue, 28 Feb 2023 19:58:56 +0100 Subject: [PATCH 0956/1444] New translations _category_.json (Hindi) --- .../clarity/noteworthy-contracts/_category_.json | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/i18n/hi/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/_category_.json b/i18n/hi/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/_category_.json index f5de305558..14b9388b4d 100644 --- a/i18n/hi/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/_category_.json +++ b/i18n/hi/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/_category_.json @@ -1,8 +1,8 @@ { - "label": "Noteworthy Contracts", - "position": 4, - "link": { - "type": "generated-index", - "description": "Specific deployed Clarity Contracts worth mentioning." - } -} \ No newline at end of file + "label": "Noteworthy Contracts", + "position": 4, + "link": { + "type": "generated-index", + "description": "Specific deployed Clarity Contracts worth mentioning." + } +} From a58bba61cb3c58bc87bb768618ec142203e9e2ff Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Thu, 9 Mar 2023 19:53:39 +0100 Subject: [PATCH 0957/1444] Update source file crash-course.md --- docs/clarity/crash-course.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/clarity/crash-course.md b/docs/clarity/crash-course.md index 4e3b07ebba..89a864e9c6 100644 --- a/docs/clarity/crash-course.md +++ b/docs/clarity/crash-course.md @@ -39,7 +39,7 @@ Clarity takes inspiration from LISP, and you can think of everything in Clarity 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.md). +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. @@ -51,7 +51,7 @@ Why am I describing this as if we are calling a function? Because we are, and it Let's expand on this concept a bit by deleting this and writing a new function. -```clojure +```clarity (define-data-var count int 0) (define-public (add-number (number int)) (let @@ -102,7 +102,7 @@ So this `let` function is a way of wrapping a multi-step function into a single But it does one other crucial thing at the beginning. This line: -```clojure +```clarity (current-count count) ``` From 960f135598624059de427bbcfe53ab73776ba3ad Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Thu, 9 Mar 2023 19:53:54 +0100 Subject: [PATCH 0958/1444] Update source file _category_.json --- docs/clarity/noteworthy-contracts/_category_.json | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/clarity/noteworthy-contracts/_category_.json b/docs/clarity/noteworthy-contracts/_category_.json index 77867c9414..14b9388b4d 100644 --- a/docs/clarity/noteworthy-contracts/_category_.json +++ b/docs/clarity/noteworthy-contracts/_category_.json @@ -1,8 +1,8 @@ { - "label": "Noteworthy Contracts", - "position": 4, - "link": { - "type": "generated-index", - "description": "Specific deployed Clarity Contracts worth mentioning." - } - } \ No newline at end of file + "label": "Noteworthy Contracts", + "position": 4, + "link": { + "type": "generated-index", + "description": "Specific deployed Clarity Contracts worth mentioning." + } +} From 72bdb5c478251aa2951229c6caa2178bba4ef880 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Thu, 9 Mar 2023 19:54:04 +0100 Subject: [PATCH 0959/1444] New translations satoshis-ridge.md (French) --- .../current/tutorials/satoshis-ridge.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/tutorials/satoshis-ridge.md b/i18n/fr/docusaurus-plugin-content-docs/current/tutorials/satoshis-ridge.md index 596339ae74..0c72f41b88 100644 --- a/i18n/fr/docusaurus-plugin-content-docs/current/tutorials/satoshis-ridge.md +++ b/i18n/fr/docusaurus-plugin-content-docs/current/tutorials/satoshis-ridge.md @@ -38,9 +38,9 @@ While you won't need to do any actual Bitcoin programming, it will be very helpf ## 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 arguable one of its strengths. +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 modify 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. +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. From 0dcc6c5d2931d8d9172681d14545b52572baa90f Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Thu, 9 Mar 2023 19:54:05 +0100 Subject: [PATCH 0960/1444] New translations satoshis-ridge.md (Spanish) --- .../current/tutorials/satoshis-ridge.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/i18n/es/docusaurus-plugin-content-docs/current/tutorials/satoshis-ridge.md b/i18n/es/docusaurus-plugin-content-docs/current/tutorials/satoshis-ridge.md index ee7482804c..84f6723c16 100644 --- a/i18n/es/docusaurus-plugin-content-docs/current/tutorials/satoshis-ridge.md +++ b/i18n/es/docusaurus-plugin-content-docs/current/tutorials/satoshis-ridge.md @@ -38,9 +38,9 @@ While you won't need to do any actual Bitcoin programming, it will be very helpf ## 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 arguable one of its strengths. +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 modify 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. +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. From 4c422cfaa1ce162ed29c9b4f2a1ca516ce4c9c13 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Thu, 9 Mar 2023 19:54:06 +0100 Subject: [PATCH 0961/1444] New translations satoshis-ridge.md (German) --- .../current/tutorials/satoshis-ridge.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/i18n/de/docusaurus-plugin-content-docs/current/tutorials/satoshis-ridge.md b/i18n/de/docusaurus-plugin-content-docs/current/tutorials/satoshis-ridge.md index 596339ae74..0c72f41b88 100644 --- a/i18n/de/docusaurus-plugin-content-docs/current/tutorials/satoshis-ridge.md +++ b/i18n/de/docusaurus-plugin-content-docs/current/tutorials/satoshis-ridge.md @@ -38,9 +38,9 @@ While you won't need to do any actual Bitcoin programming, it will be very helpf ## 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 arguable one of its strengths. +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 modify 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. +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. From f73c2db5a210fb6ede51620449266716741ff23d Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Thu, 9 Mar 2023 19:54:07 +0100 Subject: [PATCH 0962/1444] New translations satoshis-ridge.md (Japanese) --- .../current/tutorials/satoshis-ridge.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/tutorials/satoshis-ridge.md b/i18n/ja/docusaurus-plugin-content-docs/current/tutorials/satoshis-ridge.md index 596339ae74..0c72f41b88 100644 --- a/i18n/ja/docusaurus-plugin-content-docs/current/tutorials/satoshis-ridge.md +++ b/i18n/ja/docusaurus-plugin-content-docs/current/tutorials/satoshis-ridge.md @@ -38,9 +38,9 @@ While you won't need to do any actual Bitcoin programming, it will be very helpf ## 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 arguable one of its strengths. +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 modify 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. +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. From 8f24b1faa832d84473505ff21f441c646f16b0cf Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Thu, 9 Mar 2023 19:54:08 +0100 Subject: [PATCH 0963/1444] New translations satoshis-ridge.md (Korean) --- .../current/tutorials/satoshis-ridge.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/i18n/ko/docusaurus-plugin-content-docs/current/tutorials/satoshis-ridge.md b/i18n/ko/docusaurus-plugin-content-docs/current/tutorials/satoshis-ridge.md index 596339ae74..0c72f41b88 100644 --- a/i18n/ko/docusaurus-plugin-content-docs/current/tutorials/satoshis-ridge.md +++ b/i18n/ko/docusaurus-plugin-content-docs/current/tutorials/satoshis-ridge.md @@ -38,9 +38,9 @@ While you won't need to do any actual Bitcoin programming, it will be very helpf ## 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 arguable one of its strengths. +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 modify 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. +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. From 1390ef8ccc783a1b1f2902c0f2aa1ad3729fae7b Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Thu, 9 Mar 2023 19:54:09 +0100 Subject: [PATCH 0964/1444] New translations satoshis-ridge.md (Russian) --- .../current/tutorials/satoshis-ridge.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/tutorials/satoshis-ridge.md b/i18n/ru/docusaurus-plugin-content-docs/current/tutorials/satoshis-ridge.md index 596339ae74..0c72f41b88 100644 --- a/i18n/ru/docusaurus-plugin-content-docs/current/tutorials/satoshis-ridge.md +++ b/i18n/ru/docusaurus-plugin-content-docs/current/tutorials/satoshis-ridge.md @@ -38,9 +38,9 @@ While you won't need to do any actual Bitcoin programming, it will be very helpf ## 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 arguable one of its strengths. +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 modify 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. +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. From 93e759a6ebaf0ebc43e67762115ef0d437ae9dee Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Thu, 9 Mar 2023 19:54:10 +0100 Subject: [PATCH 0965/1444] New translations satoshis-ridge.md (Turkish) --- .../current/tutorials/satoshis-ridge.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/i18n/tr/docusaurus-plugin-content-docs/current/tutorials/satoshis-ridge.md b/i18n/tr/docusaurus-plugin-content-docs/current/tutorials/satoshis-ridge.md index 596339ae74..0c72f41b88 100644 --- a/i18n/tr/docusaurus-plugin-content-docs/current/tutorials/satoshis-ridge.md +++ b/i18n/tr/docusaurus-plugin-content-docs/current/tutorials/satoshis-ridge.md @@ -38,9 +38,9 @@ While you won't need to do any actual Bitcoin programming, it will be very helpf ## 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 arguable one of its strengths. +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 modify 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. +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. From b447509fc5e961e5bd6d9fa747cb70b6bcaea8f4 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Thu, 9 Mar 2023 19:54:11 +0100 Subject: [PATCH 0966/1444] New translations satoshis-ridge.md (Chinese Simplified) --- .../current/tutorials/satoshis-ridge.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/tutorials/satoshis-ridge.md b/i18n/zh/docusaurus-plugin-content-docs/current/tutorials/satoshis-ridge.md index 596339ae74..0c72f41b88 100644 --- a/i18n/zh/docusaurus-plugin-content-docs/current/tutorials/satoshis-ridge.md +++ b/i18n/zh/docusaurus-plugin-content-docs/current/tutorials/satoshis-ridge.md @@ -38,9 +38,9 @@ While you won't need to do any actual Bitcoin programming, it will be very helpf ## 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 arguable one of its strengths. +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 modify 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. +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. From 4db93c752edf03df1e5ec19ea8552f902405826e Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Thu, 9 Mar 2023 19:54:12 +0100 Subject: [PATCH 0967/1444] New translations satoshis-ridge.md (Vietnamese) --- .../current/tutorials/satoshis-ridge.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/i18n/vi/docusaurus-plugin-content-docs/current/tutorials/satoshis-ridge.md b/i18n/vi/docusaurus-plugin-content-docs/current/tutorials/satoshis-ridge.md index 596339ae74..0c72f41b88 100644 --- a/i18n/vi/docusaurus-plugin-content-docs/current/tutorials/satoshis-ridge.md +++ b/i18n/vi/docusaurus-plugin-content-docs/current/tutorials/satoshis-ridge.md @@ -38,9 +38,9 @@ While you won't need to do any actual Bitcoin programming, it will be very helpf ## 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 arguable one of its strengths. +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 modify 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. +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. From 81d687a4814e024746167e6c6de4186639e7e4b0 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Thu, 9 Mar 2023 19:54:13 +0100 Subject: [PATCH 0968/1444] New translations satoshis-ridge.md (Portuguese, Brazilian) --- .../current/tutorials/satoshis-ridge.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/i18n/pt/docusaurus-plugin-content-docs/current/tutorials/satoshis-ridge.md b/i18n/pt/docusaurus-plugin-content-docs/current/tutorials/satoshis-ridge.md index 596339ae74..0c72f41b88 100644 --- a/i18n/pt/docusaurus-plugin-content-docs/current/tutorials/satoshis-ridge.md +++ b/i18n/pt/docusaurus-plugin-content-docs/current/tutorials/satoshis-ridge.md @@ -38,9 +38,9 @@ While you won't need to do any actual Bitcoin programming, it will be very helpf ## 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 arguable one of its strengths. +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 modify 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. +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. From 935f6ba54b1926b66180a1fabfee398727146242 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Thu, 9 Mar 2023 19:54:13 +0100 Subject: [PATCH 0969/1444] New translations satoshis-ridge.md (Indonesian) --- .../current/tutorials/satoshis-ridge.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/i18n/id/docusaurus-plugin-content-docs/current/tutorials/satoshis-ridge.md b/i18n/id/docusaurus-plugin-content-docs/current/tutorials/satoshis-ridge.md index 78b5079d15..e71039e310 100644 --- a/i18n/id/docusaurus-plugin-content-docs/current/tutorials/satoshis-ridge.md +++ b/i18n/id/docusaurus-plugin-content-docs/current/tutorials/satoshis-ridge.md @@ -38,9 +38,9 @@ While you won't need to do any actual Bitcoin programming, it will be very helpf ## 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 arguable one of its strengths. +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 modify 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. +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. From 34b6ee21d3bb86a9b57789eea1a80a59ec4f53c8 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Thu, 9 Mar 2023 19:54:14 +0100 Subject: [PATCH 0970/1444] New translations satoshis-ridge.md (Hindi) --- .../current/tutorials/satoshis-ridge.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/i18n/hi/docusaurus-plugin-content-docs/current/tutorials/satoshis-ridge.md b/i18n/hi/docusaurus-plugin-content-docs/current/tutorials/satoshis-ridge.md index 596339ae74..0c72f41b88 100644 --- a/i18n/hi/docusaurus-plugin-content-docs/current/tutorials/satoshis-ridge.md +++ b/i18n/hi/docusaurus-plugin-content-docs/current/tutorials/satoshis-ridge.md @@ -38,9 +38,9 @@ While you won't need to do any actual Bitcoin programming, it will be very helpf ## 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 arguable one of its strengths. +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 modify 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. +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. From 68cb241a96ca9a87523074093a25ad1e06934636 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Mon, 13 Mar 2023 20:36:21 +0100 Subject: [PATCH 0971/1444] Update source file satoshis-ridge.md --- docs/tutorials/satoshis-ridge.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/tutorials/satoshis-ridge.md b/docs/tutorials/satoshis-ridge.md index 596339ae74..0c72f41b88 100644 --- a/docs/tutorials/satoshis-ridge.md +++ b/docs/tutorials/satoshis-ridge.md @@ -38,9 +38,9 @@ While you won't need to do any actual Bitcoin programming, it will be very helpf ## 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 arguable one of its strengths. +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 modify 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. +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. From 425626823e1aaf0c062766592da0d89aa7364d3c Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Wed, 22 Mar 2023 21:35:07 +0100 Subject: [PATCH 0972/1444] New translations sips.md (French) --- .../current/stacks-academy/sips.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/stacks-academy/sips.md b/i18n/fr/docusaurus-plugin-content-docs/current/stacks-academy/sips.md index aa2db18e62..592021dc6b 100644 --- a/i18n/fr/docusaurus-plugin-content-docs/current/stacks-academy/sips.md +++ b/i18n/fr/docusaurus-plugin-content-docs/current/stacks-academy/sips.md @@ -17,7 +17,7 @@ The SIPs are located in the [stacksgov/sips](https://github.com/stacksgov/sips) 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/IJ15791776) to your calendar. +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) @@ -37,7 +37,10 @@ More details of the meetings are available [here](https://github.com/stacksgov/s - [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 From a670f68a464790a2da77f00faad10e5a5dedf146 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Wed, 22 Mar 2023 21:35:08 +0100 Subject: [PATCH 0973/1444] New translations sips.md (Spanish) --- .../current/stacks-academy/sips.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/i18n/es/docusaurus-plugin-content-docs/current/stacks-academy/sips.md b/i18n/es/docusaurus-plugin-content-docs/current/stacks-academy/sips.md index aa2db18e62..592021dc6b 100644 --- a/i18n/es/docusaurus-plugin-content-docs/current/stacks-academy/sips.md +++ b/i18n/es/docusaurus-plugin-content-docs/current/stacks-academy/sips.md @@ -17,7 +17,7 @@ The SIPs are located in the [stacksgov/sips](https://github.com/stacksgov/sips) 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/IJ15791776) to your calendar. +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) @@ -37,7 +37,10 @@ More details of the meetings are available [here](https://github.com/stacksgov/s - [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 From 22a5bcec9d8a69c298eb8895b196ae1830846089 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Wed, 22 Mar 2023 21:35:08 +0100 Subject: [PATCH 0974/1444] New translations sips.md (German) --- .../current/stacks-academy/sips.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/i18n/de/docusaurus-plugin-content-docs/current/stacks-academy/sips.md b/i18n/de/docusaurus-plugin-content-docs/current/stacks-academy/sips.md index aa2db18e62..592021dc6b 100644 --- a/i18n/de/docusaurus-plugin-content-docs/current/stacks-academy/sips.md +++ b/i18n/de/docusaurus-plugin-content-docs/current/stacks-academy/sips.md @@ -17,7 +17,7 @@ The SIPs are located in the [stacksgov/sips](https://github.com/stacksgov/sips) 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/IJ15791776) to your calendar. +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) @@ -37,7 +37,10 @@ More details of the meetings are available [here](https://github.com/stacksgov/s - [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 From 5cf23d9f7b9b403962b009731ad1662f80631942 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Wed, 22 Mar 2023 21:35:09 +0100 Subject: [PATCH 0975/1444] New translations sips.md (Japanese) --- .../current/stacks-academy/sips.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/stacks-academy/sips.md b/i18n/ja/docusaurus-plugin-content-docs/current/stacks-academy/sips.md index aa2db18e62..592021dc6b 100644 --- a/i18n/ja/docusaurus-plugin-content-docs/current/stacks-academy/sips.md +++ b/i18n/ja/docusaurus-plugin-content-docs/current/stacks-academy/sips.md @@ -17,7 +17,7 @@ The SIPs are located in the [stacksgov/sips](https://github.com/stacksgov/sips) 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/IJ15791776) to your calendar. +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) @@ -37,7 +37,10 @@ More details of the meetings are available [here](https://github.com/stacksgov/s - [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 From 5fd5f66364e1c5bc56d256b1298e452bb91d6cdb Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Wed, 22 Mar 2023 21:35:11 +0100 Subject: [PATCH 0976/1444] New translations sips.md (Korean) --- .../current/stacks-academy/sips.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/i18n/ko/docusaurus-plugin-content-docs/current/stacks-academy/sips.md b/i18n/ko/docusaurus-plugin-content-docs/current/stacks-academy/sips.md index aa2db18e62..592021dc6b 100644 --- a/i18n/ko/docusaurus-plugin-content-docs/current/stacks-academy/sips.md +++ b/i18n/ko/docusaurus-plugin-content-docs/current/stacks-academy/sips.md @@ -17,7 +17,7 @@ The SIPs are located in the [stacksgov/sips](https://github.com/stacksgov/sips) 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/IJ15791776) to your calendar. +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) @@ -37,7 +37,10 @@ More details of the meetings are available [here](https://github.com/stacksgov/s - [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 From 9a9c3967e3626fd43fe9a5b31707e5517505b7f7 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Wed, 22 Mar 2023 21:35:11 +0100 Subject: [PATCH 0977/1444] New translations sips.md (Russian) --- .../current/stacks-academy/sips.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/stacks-academy/sips.md b/i18n/ru/docusaurus-plugin-content-docs/current/stacks-academy/sips.md index aa2db18e62..592021dc6b 100644 --- a/i18n/ru/docusaurus-plugin-content-docs/current/stacks-academy/sips.md +++ b/i18n/ru/docusaurus-plugin-content-docs/current/stacks-academy/sips.md @@ -17,7 +17,7 @@ The SIPs are located in the [stacksgov/sips](https://github.com/stacksgov/sips) 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/IJ15791776) to your calendar. +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) @@ -37,7 +37,10 @@ More details of the meetings are available [here](https://github.com/stacksgov/s - [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 From 73e0eb67af0d4bf6377f3e9009129f71009e56d9 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Wed, 22 Mar 2023 21:35:12 +0100 Subject: [PATCH 0978/1444] New translations sips.md (Turkish) --- .../current/stacks-academy/sips.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/i18n/tr/docusaurus-plugin-content-docs/current/stacks-academy/sips.md b/i18n/tr/docusaurus-plugin-content-docs/current/stacks-academy/sips.md index aa2db18e62..592021dc6b 100644 --- a/i18n/tr/docusaurus-plugin-content-docs/current/stacks-academy/sips.md +++ b/i18n/tr/docusaurus-plugin-content-docs/current/stacks-academy/sips.md @@ -17,7 +17,7 @@ The SIPs are located in the [stacksgov/sips](https://github.com/stacksgov/sips) 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/IJ15791776) to your calendar. +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) @@ -37,7 +37,10 @@ More details of the meetings are available [here](https://github.com/stacksgov/s - [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 From 354ab948f8e9d67cb8813c9b99451ceb2a9fb1ae Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Wed, 22 Mar 2023 21:35:13 +0100 Subject: [PATCH 0979/1444] New translations sips.md (Chinese Simplified) --- .../current/stacks-academy/sips.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/stacks-academy/sips.md b/i18n/zh/docusaurus-plugin-content-docs/current/stacks-academy/sips.md index aa2db18e62..592021dc6b 100644 --- a/i18n/zh/docusaurus-plugin-content-docs/current/stacks-academy/sips.md +++ b/i18n/zh/docusaurus-plugin-content-docs/current/stacks-academy/sips.md @@ -17,7 +17,7 @@ The SIPs are located in the [stacksgov/sips](https://github.com/stacksgov/sips) 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/IJ15791776) to your calendar. +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) @@ -37,7 +37,10 @@ More details of the meetings are available [here](https://github.com/stacksgov/s - [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 From 339b6cc84bb052c08eb0a8c058074609838334dc Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Wed, 22 Mar 2023 21:35:14 +0100 Subject: [PATCH 0980/1444] New translations sips.md (Vietnamese) --- .../current/stacks-academy/sips.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/i18n/vi/docusaurus-plugin-content-docs/current/stacks-academy/sips.md b/i18n/vi/docusaurus-plugin-content-docs/current/stacks-academy/sips.md index aa2db18e62..592021dc6b 100644 --- a/i18n/vi/docusaurus-plugin-content-docs/current/stacks-academy/sips.md +++ b/i18n/vi/docusaurus-plugin-content-docs/current/stacks-academy/sips.md @@ -17,7 +17,7 @@ The SIPs are located in the [stacksgov/sips](https://github.com/stacksgov/sips) 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/IJ15791776) to your calendar. +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) @@ -37,7 +37,10 @@ More details of the meetings are available [here](https://github.com/stacksgov/s - [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 From f2d73154a96f2de07b535e226997d5849d778d50 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Wed, 22 Mar 2023 21:35:15 +0100 Subject: [PATCH 0981/1444] New translations sips.md (Portuguese, Brazilian) --- .../current/stacks-academy/sips.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/i18n/pt/docusaurus-plugin-content-docs/current/stacks-academy/sips.md b/i18n/pt/docusaurus-plugin-content-docs/current/stacks-academy/sips.md index aa2db18e62..592021dc6b 100644 --- a/i18n/pt/docusaurus-plugin-content-docs/current/stacks-academy/sips.md +++ b/i18n/pt/docusaurus-plugin-content-docs/current/stacks-academy/sips.md @@ -17,7 +17,7 @@ The SIPs are located in the [stacksgov/sips](https://github.com/stacksgov/sips) 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/IJ15791776) to your calendar. +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) @@ -37,7 +37,10 @@ More details of the meetings are available [here](https://github.com/stacksgov/s - [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 From 5701e055e409da3f50790d4148b85fa8c7c15824 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Wed, 22 Mar 2023 21:35:16 +0100 Subject: [PATCH 0982/1444] New translations sips.md (Indonesian) --- .../current/stacks-academy/sips.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/i18n/id/docusaurus-plugin-content-docs/current/stacks-academy/sips.md b/i18n/id/docusaurus-plugin-content-docs/current/stacks-academy/sips.md index aa2db18e62..592021dc6b 100644 --- a/i18n/id/docusaurus-plugin-content-docs/current/stacks-academy/sips.md +++ b/i18n/id/docusaurus-plugin-content-docs/current/stacks-academy/sips.md @@ -17,7 +17,7 @@ The SIPs are located in the [stacksgov/sips](https://github.com/stacksgov/sips) 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/IJ15791776) to your calendar. +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) @@ -37,7 +37,10 @@ More details of the meetings are available [here](https://github.com/stacksgov/s - [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 From 6a41c056b25f800b446780b091c7670093a3f6b6 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Wed, 22 Mar 2023 21:35:17 +0100 Subject: [PATCH 0983/1444] New translations sips.md (Hindi) --- .../current/stacks-academy/sips.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/i18n/hi/docusaurus-plugin-content-docs/current/stacks-academy/sips.md b/i18n/hi/docusaurus-plugin-content-docs/current/stacks-academy/sips.md index aa2db18e62..592021dc6b 100644 --- a/i18n/hi/docusaurus-plugin-content-docs/current/stacks-academy/sips.md +++ b/i18n/hi/docusaurus-plugin-content-docs/current/stacks-academy/sips.md @@ -17,7 +17,7 @@ The SIPs are located in the [stacksgov/sips](https://github.com/stacksgov/sips) 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/IJ15791776) to your calendar. +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) @@ -37,7 +37,10 @@ More details of the meetings are available [here](https://github.com/stacksgov/s - [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 From 53c65bd044f7de95763dab7c23c713f412a5b0e7 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Wed, 22 Mar 2023 22:43:44 +0100 Subject: [PATCH 0984/1444] Update source file sips.md --- docs/stacks-academy/sips.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/docs/stacks-academy/sips.md b/docs/stacks-academy/sips.md index 1397b6a65f..c70cc5866b 100644 --- a/docs/stacks-academy/sips.md +++ b/docs/stacks-academy/sips.md @@ -17,7 +17,7 @@ The SIPs are located in the [stacksgov/sips](https://github.com/stacksgov/sips) 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/IJ15791776) to your calendar. +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) @@ -37,7 +37,10 @@ More details of the meetings are available [here](https://github.com/stacksgov/s - [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 From 7115aa771265f7ffd68bf274bc6ae3a20b999b3e Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Thu, 23 Mar 2023 21:29:35 +0100 Subject: [PATCH 0985/1444] New translations btc-connection.md (French) --- .../current/stacks-academy/btc-connection.md | 81 ++++++++++++++----- 1 file changed, 61 insertions(+), 20 deletions(-) diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/stacks-academy/btc-connection.md b/i18n/fr/docusaurus-plugin-content-docs/current/stacks-academy/btc-connection.md index b4db915969..a3dd62f9ff 100644 --- a/i18n/fr/docusaurus-plugin-content-docs/current/stacks-academy/btc-connection.md +++ b/i18n/fr/docusaurus-plugin-content-docs/current/stacks-academy/btc-connection.md @@ -14,13 +14,37 @@ This topic is a bit of a rabbit hole, and this section of Stacks Academy is pret Let's get into it. -## Stacks Among Other Bitcoin Layers +## 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: -In the [last section](./what-is-stacks.md) we covered what Stacks actually is and what problem it is solving, but this is not a new problem. The Bitcoin write problem has been a bit of a holy grail problem in the crypto world for a while now. +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. -Bitcoin is the OG cryptocurrency and has the largest market cap, but it also some of the least functionality, which means if we want to make it a productive asset and use it to build a decentralized economy, we need to take a layered approach and let Bitcoin do what it does best, while creating additional layers on top of it to add functionality. +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. -So how does Stacks compare to some of the other approaches to layering on top of Bitcoin? +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 @@ -56,6 +80,32 @@ The Liquid consensus mechanism is managed by 15 functionaries, who handle the tr 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 follow Bitcoin finality with 100% Bitcoin hashpower. 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 designers of the Nakamoto release have decided to wait for 150 blocks before Bitcoin finality kicks in; this is mostly done to allow short-term forks to be resolved at the Stacks level. This design also means that most Maximal Extractable Value (MEV) action happens on the Stacks layer side and not on the Bitcoin side. There is always a fear of MEV incentives messing with Bitcoin mining, and the Stacks layer explicitly attracts most MEV activity to happen on the Stacks layer vs. Bitcoin L1 (the assumption here is that most MEV activity will occur within 150 blocks). Changing the variable from 150 to 6 blocks is trivial technically and can be configured as needed. Sovereign rollups effectively use a variable of 0 blocks and work similarly to the Stacks layer for reorg resistance. + +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. @@ -70,27 +120,18 @@ This is why networks like Lightning and other P2P networks don't need tokens, th 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. -But because it has its own execution environment and smart contract state to maintain, it needs a token to incentivize maintenance of the network. - -But it goes further than that. It is possible to build a system like this without a token using something like merge-mining or a sidechain, but then we lose out on the additional benefit of having the chain state's safety underpinned by its entire token economy's value. - -In the case of Stacks, the safety and liveness of the chain are underpinned by this value, and the stacking mechanism incentivizes network members to increase this value. - -From Jude Nelson, Stacks core developer: - -"How hard is it to cause a safety failure (i.e. a double-spend via a reorg) on just the canonical Stacks chain fork? Anyone can become a miner by spending BTC, so without loss of generality, reverting the last block on the canonical chain is at least as hard in expectation as spending more BTC than the rest of the miners combined for that block. Because each Bitcoin block selects at most one Stacks block, the act of reorging the canonical Stacks chain back N blocks is the act of winning at least N + 1 blocks built off of a common ancestor that is N blocks deep. This is a lower bound on the number of Bitcoin blocks mined during which a reorg needs to take place — in practice, honest miners will keep working on the canonical chain, and will win some Stacks blocks of their own, which in turn increases the number of Stacks blocks the reorging miners must win. - -How costly is it to carry out a reorg of N blocks? It’s a function of how valuable STX is relative to BTC — the more valuable STX are, the more BTC honest miners are committing to mining (this has borne out in practice), and thus the more BTC a reorging miner must commit. Therefore, the cost of a reorg is a function of the value of STX. +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. -This is similar to the economic security of a PoW blockchain. Like in PoW, each fork of the Stacks chain has its own independent “security budget” — an attacker must out-spend the security budget to carry out a reorg, and the security budget is a function of the block rewards. In PoX, the only difference is that the miners spend another blockchain’s tokens (BTC in Stacks’ case) instead of energy. Therefore, Stacks can’t be a sidechain, a drivechain, or a merge-mined chain, because none of these other systems’ security budgets are a function of their tokens’ worth. Sidechains, drivechains, and merged-mined chains all rely on external miners for their safety, since their safety is guaranteed in part by external miners validating their blocks. The onus on these systems is to get external miners to care enough to do so, and in the case of sidechains, drivechains, and blind merged-mined chains, there is an additional onus to encourage their nodes to mine blocks at all (since there is no on-chain reward for them to earn by doing so). By contrast, disinterested Bitcoin miners neither assist nor prevent a reorg in PoX — they only record the history of all Stacks forks. +The Stacks token (STX) is primarily meant to be used for two things (details in Stacks paper): -PoX offers two additional, unique security properties on top of PoW. First, no matter how much BTC a reorging miner can commit, the act of executing a reorg is going to be time-consuming. Unless the attacker can attack the Bitcoin chain itself by quickly producing a better Bitcoin fork, a reorging miner must sustain the attack for at least N + 1 Bitcoin blocks. This gives honest miners and users ample time to notice and react to the reorg attempt. +1. Incentives for Stacks L2 miners +2. Incentives for peg-out signers -Second, the history of block production in all Stacks forks is embedded within Bitcoin. This allows the system to leverage Bitcoin’s security budget in order to ensure that all forks are public. This is because the act of producing a hidden Stacks fork, where the fork’s block hashes are not known to the honest miners, is the act of producing a hidden canonical Bitcoin fork. Therefore, the act of producing a hidden Stacks fork is at least as hard as reorging the Bitcoin chain. A PoX chain leverages this property not to prevent reorgs, but to make reorgs unprofitable. +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. -By anchoring blocks to an existing blockchain, a PoX chain forces reorgs to happen out in the open, thereby giving advance warning to all honest network participants when they happen. Honest miners, users, and exchanges will see the PoX transactions for reorg attempts on the existing blockchain, and adapt their behaviors accordingly: honest miners will increase their commitments, and users and exchanges will require more confirmations for transactions. This makes the act of carrying out a reorg while also making a profit much more challenging, since malicious reorgs — like selfish mining and double-spending — rely on secrecy to work effectively. Specific to Stacks, miners are additionally required to mine for a “warm-up” period of two blocks, during which they must spend BTC at their target commit levels but will not win any Stacks blocks. So, a high-budget reorg attempt will not only be costly, but will also alert the rest of the network before the damage is done." +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. -- [What Kind of Blockchain is Stacks?](https://stacks.org/stacks-blockchain) +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 From 4917ba09a089367af2945b6f2702dcb167da94e3 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Thu, 23 Mar 2023 21:29:36 +0100 Subject: [PATCH 0986/1444] New translations btc-connection.md (Spanish) --- .../current/stacks-academy/btc-connection.md | 81 ++++++++++++++----- 1 file changed, 61 insertions(+), 20 deletions(-) diff --git a/i18n/es/docusaurus-plugin-content-docs/current/stacks-academy/btc-connection.md b/i18n/es/docusaurus-plugin-content-docs/current/stacks-academy/btc-connection.md index b4db915969..a3dd62f9ff 100644 --- a/i18n/es/docusaurus-plugin-content-docs/current/stacks-academy/btc-connection.md +++ b/i18n/es/docusaurus-plugin-content-docs/current/stacks-academy/btc-connection.md @@ -14,13 +14,37 @@ This topic is a bit of a rabbit hole, and this section of Stacks Academy is pret Let's get into it. -## Stacks Among Other Bitcoin Layers +## 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: -In the [last section](./what-is-stacks.md) we covered what Stacks actually is and what problem it is solving, but this is not a new problem. The Bitcoin write problem has been a bit of a holy grail problem in the crypto world for a while now. +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. -Bitcoin is the OG cryptocurrency and has the largest market cap, but it also some of the least functionality, which means if we want to make it a productive asset and use it to build a decentralized economy, we need to take a layered approach and let Bitcoin do what it does best, while creating additional layers on top of it to add functionality. +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. -So how does Stacks compare to some of the other approaches to layering on top of Bitcoin? +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 @@ -56,6 +80,32 @@ The Liquid consensus mechanism is managed by 15 functionaries, who handle the tr 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 follow Bitcoin finality with 100% Bitcoin hashpower. 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 designers of the Nakamoto release have decided to wait for 150 blocks before Bitcoin finality kicks in; this is mostly done to allow short-term forks to be resolved at the Stacks level. This design also means that most Maximal Extractable Value (MEV) action happens on the Stacks layer side and not on the Bitcoin side. There is always a fear of MEV incentives messing with Bitcoin mining, and the Stacks layer explicitly attracts most MEV activity to happen on the Stacks layer vs. Bitcoin L1 (the assumption here is that most MEV activity will occur within 150 blocks). Changing the variable from 150 to 6 blocks is trivial technically and can be configured as needed. Sovereign rollups effectively use a variable of 0 blocks and work similarly to the Stacks layer for reorg resistance. + +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. @@ -70,27 +120,18 @@ This is why networks like Lightning and other P2P networks don't need tokens, th 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. -But because it has its own execution environment and smart contract state to maintain, it needs a token to incentivize maintenance of the network. - -But it goes further than that. It is possible to build a system like this without a token using something like merge-mining or a sidechain, but then we lose out on the additional benefit of having the chain state's safety underpinned by its entire token economy's value. - -In the case of Stacks, the safety and liveness of the chain are underpinned by this value, and the stacking mechanism incentivizes network members to increase this value. - -From Jude Nelson, Stacks core developer: - -"How hard is it to cause a safety failure (i.e. a double-spend via a reorg) on just the canonical Stacks chain fork? Anyone can become a miner by spending BTC, so without loss of generality, reverting the last block on the canonical chain is at least as hard in expectation as spending more BTC than the rest of the miners combined for that block. Because each Bitcoin block selects at most one Stacks block, the act of reorging the canonical Stacks chain back N blocks is the act of winning at least N + 1 blocks built off of a common ancestor that is N blocks deep. This is a lower bound on the number of Bitcoin blocks mined during which a reorg needs to take place — in practice, honest miners will keep working on the canonical chain, and will win some Stacks blocks of their own, which in turn increases the number of Stacks blocks the reorging miners must win. - -How costly is it to carry out a reorg of N blocks? It’s a function of how valuable STX is relative to BTC — the more valuable STX are, the more BTC honest miners are committing to mining (this has borne out in practice), and thus the more BTC a reorging miner must commit. Therefore, the cost of a reorg is a function of the value of STX. +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. -This is similar to the economic security of a PoW blockchain. Like in PoW, each fork of the Stacks chain has its own independent “security budget” — an attacker must out-spend the security budget to carry out a reorg, and the security budget is a function of the block rewards. In PoX, the only difference is that the miners spend another blockchain’s tokens (BTC in Stacks’ case) instead of energy. Therefore, Stacks can’t be a sidechain, a drivechain, or a merge-mined chain, because none of these other systems’ security budgets are a function of their tokens’ worth. Sidechains, drivechains, and merged-mined chains all rely on external miners for their safety, since their safety is guaranteed in part by external miners validating their blocks. The onus on these systems is to get external miners to care enough to do so, and in the case of sidechains, drivechains, and blind merged-mined chains, there is an additional onus to encourage their nodes to mine blocks at all (since there is no on-chain reward for them to earn by doing so). By contrast, disinterested Bitcoin miners neither assist nor prevent a reorg in PoX — they only record the history of all Stacks forks. +The Stacks token (STX) is primarily meant to be used for two things (details in Stacks paper): -PoX offers two additional, unique security properties on top of PoW. First, no matter how much BTC a reorging miner can commit, the act of executing a reorg is going to be time-consuming. Unless the attacker can attack the Bitcoin chain itself by quickly producing a better Bitcoin fork, a reorging miner must sustain the attack for at least N + 1 Bitcoin blocks. This gives honest miners and users ample time to notice and react to the reorg attempt. +1. Incentives for Stacks L2 miners +2. Incentives for peg-out signers -Second, the history of block production in all Stacks forks is embedded within Bitcoin. This allows the system to leverage Bitcoin’s security budget in order to ensure that all forks are public. This is because the act of producing a hidden Stacks fork, where the fork’s block hashes are not known to the honest miners, is the act of producing a hidden canonical Bitcoin fork. Therefore, the act of producing a hidden Stacks fork is at least as hard as reorging the Bitcoin chain. A PoX chain leverages this property not to prevent reorgs, but to make reorgs unprofitable. +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. -By anchoring blocks to an existing blockchain, a PoX chain forces reorgs to happen out in the open, thereby giving advance warning to all honest network participants when they happen. Honest miners, users, and exchanges will see the PoX transactions for reorg attempts on the existing blockchain, and adapt their behaviors accordingly: honest miners will increase their commitments, and users and exchanges will require more confirmations for transactions. This makes the act of carrying out a reorg while also making a profit much more challenging, since malicious reorgs — like selfish mining and double-spending — rely on secrecy to work effectively. Specific to Stacks, miners are additionally required to mine for a “warm-up” period of two blocks, during which they must spend BTC at their target commit levels but will not win any Stacks blocks. So, a high-budget reorg attempt will not only be costly, but will also alert the rest of the network before the damage is done." +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. -- [What Kind of Blockchain is Stacks?](https://stacks.org/stacks-blockchain) +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 From 2ca0d023bbf75736a3f91f31d18217978f2ec7fa Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Thu, 23 Mar 2023 21:29:37 +0100 Subject: [PATCH 0987/1444] New translations btc-connection.md (German) --- .../current/stacks-academy/btc-connection.md | 81 ++++++++++++++----- 1 file changed, 61 insertions(+), 20 deletions(-) diff --git a/i18n/de/docusaurus-plugin-content-docs/current/stacks-academy/btc-connection.md b/i18n/de/docusaurus-plugin-content-docs/current/stacks-academy/btc-connection.md index b4db915969..a3dd62f9ff 100644 --- a/i18n/de/docusaurus-plugin-content-docs/current/stacks-academy/btc-connection.md +++ b/i18n/de/docusaurus-plugin-content-docs/current/stacks-academy/btc-connection.md @@ -14,13 +14,37 @@ This topic is a bit of a rabbit hole, and this section of Stacks Academy is pret Let's get into it. -## Stacks Among Other Bitcoin Layers +## 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: -In the [last section](./what-is-stacks.md) we covered what Stacks actually is and what problem it is solving, but this is not a new problem. The Bitcoin write problem has been a bit of a holy grail problem in the crypto world for a while now. +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. -Bitcoin is the OG cryptocurrency and has the largest market cap, but it also some of the least functionality, which means if we want to make it a productive asset and use it to build a decentralized economy, we need to take a layered approach and let Bitcoin do what it does best, while creating additional layers on top of it to add functionality. +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. -So how does Stacks compare to some of the other approaches to layering on top of Bitcoin? +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 @@ -56,6 +80,32 @@ The Liquid consensus mechanism is managed by 15 functionaries, who handle the tr 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 follow Bitcoin finality with 100% Bitcoin hashpower. 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 designers of the Nakamoto release have decided to wait for 150 blocks before Bitcoin finality kicks in; this is mostly done to allow short-term forks to be resolved at the Stacks level. This design also means that most Maximal Extractable Value (MEV) action happens on the Stacks layer side and not on the Bitcoin side. There is always a fear of MEV incentives messing with Bitcoin mining, and the Stacks layer explicitly attracts most MEV activity to happen on the Stacks layer vs. Bitcoin L1 (the assumption here is that most MEV activity will occur within 150 blocks). Changing the variable from 150 to 6 blocks is trivial technically and can be configured as needed. Sovereign rollups effectively use a variable of 0 blocks and work similarly to the Stacks layer for reorg resistance. + +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. @@ -70,27 +120,18 @@ This is why networks like Lightning and other P2P networks don't need tokens, th 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. -But because it has its own execution environment and smart contract state to maintain, it needs a token to incentivize maintenance of the network. - -But it goes further than that. It is possible to build a system like this without a token using something like merge-mining or a sidechain, but then we lose out on the additional benefit of having the chain state's safety underpinned by its entire token economy's value. - -In the case of Stacks, the safety and liveness of the chain are underpinned by this value, and the stacking mechanism incentivizes network members to increase this value. - -From Jude Nelson, Stacks core developer: - -"How hard is it to cause a safety failure (i.e. a double-spend via a reorg) on just the canonical Stacks chain fork? Anyone can become a miner by spending BTC, so without loss of generality, reverting the last block on the canonical chain is at least as hard in expectation as spending more BTC than the rest of the miners combined for that block. Because each Bitcoin block selects at most one Stacks block, the act of reorging the canonical Stacks chain back N blocks is the act of winning at least N + 1 blocks built off of a common ancestor that is N blocks deep. This is a lower bound on the number of Bitcoin blocks mined during which a reorg needs to take place — in practice, honest miners will keep working on the canonical chain, and will win some Stacks blocks of their own, which in turn increases the number of Stacks blocks the reorging miners must win. - -How costly is it to carry out a reorg of N blocks? It’s a function of how valuable STX is relative to BTC — the more valuable STX are, the more BTC honest miners are committing to mining (this has borne out in practice), and thus the more BTC a reorging miner must commit. Therefore, the cost of a reorg is a function of the value of STX. +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. -This is similar to the economic security of a PoW blockchain. Like in PoW, each fork of the Stacks chain has its own independent “security budget” — an attacker must out-spend the security budget to carry out a reorg, and the security budget is a function of the block rewards. In PoX, the only difference is that the miners spend another blockchain’s tokens (BTC in Stacks’ case) instead of energy. Therefore, Stacks can’t be a sidechain, a drivechain, or a merge-mined chain, because none of these other systems’ security budgets are a function of their tokens’ worth. Sidechains, drivechains, and merged-mined chains all rely on external miners for their safety, since their safety is guaranteed in part by external miners validating their blocks. The onus on these systems is to get external miners to care enough to do so, and in the case of sidechains, drivechains, and blind merged-mined chains, there is an additional onus to encourage their nodes to mine blocks at all (since there is no on-chain reward for them to earn by doing so). By contrast, disinterested Bitcoin miners neither assist nor prevent a reorg in PoX — they only record the history of all Stacks forks. +The Stacks token (STX) is primarily meant to be used for two things (details in Stacks paper): -PoX offers two additional, unique security properties on top of PoW. First, no matter how much BTC a reorging miner can commit, the act of executing a reorg is going to be time-consuming. Unless the attacker can attack the Bitcoin chain itself by quickly producing a better Bitcoin fork, a reorging miner must sustain the attack for at least N + 1 Bitcoin blocks. This gives honest miners and users ample time to notice and react to the reorg attempt. +1. Incentives for Stacks L2 miners +2. Incentives for peg-out signers -Second, the history of block production in all Stacks forks is embedded within Bitcoin. This allows the system to leverage Bitcoin’s security budget in order to ensure that all forks are public. This is because the act of producing a hidden Stacks fork, where the fork’s block hashes are not known to the honest miners, is the act of producing a hidden canonical Bitcoin fork. Therefore, the act of producing a hidden Stacks fork is at least as hard as reorging the Bitcoin chain. A PoX chain leverages this property not to prevent reorgs, but to make reorgs unprofitable. +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. -By anchoring blocks to an existing blockchain, a PoX chain forces reorgs to happen out in the open, thereby giving advance warning to all honest network participants when they happen. Honest miners, users, and exchanges will see the PoX transactions for reorg attempts on the existing blockchain, and adapt their behaviors accordingly: honest miners will increase their commitments, and users and exchanges will require more confirmations for transactions. This makes the act of carrying out a reorg while also making a profit much more challenging, since malicious reorgs — like selfish mining and double-spending — rely on secrecy to work effectively. Specific to Stacks, miners are additionally required to mine for a “warm-up” period of two blocks, during which they must spend BTC at their target commit levels but will not win any Stacks blocks. So, a high-budget reorg attempt will not only be costly, but will also alert the rest of the network before the damage is done." +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. -- [What Kind of Blockchain is Stacks?](https://stacks.org/stacks-blockchain) +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 From 21e630f56cb47b86b4125dfbb75be53045871fe9 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Thu, 23 Mar 2023 21:29:38 +0100 Subject: [PATCH 0988/1444] New translations btc-connection.md (Japanese) --- .../current/stacks-academy/btc-connection.md | 81 ++++++++++++++----- 1 file changed, 61 insertions(+), 20 deletions(-) diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/stacks-academy/btc-connection.md b/i18n/ja/docusaurus-plugin-content-docs/current/stacks-academy/btc-connection.md index b4db915969..a3dd62f9ff 100644 --- a/i18n/ja/docusaurus-plugin-content-docs/current/stacks-academy/btc-connection.md +++ b/i18n/ja/docusaurus-plugin-content-docs/current/stacks-academy/btc-connection.md @@ -14,13 +14,37 @@ This topic is a bit of a rabbit hole, and this section of Stacks Academy is pret Let's get into it. -## Stacks Among Other Bitcoin Layers +## 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: -In the [last section](./what-is-stacks.md) we covered what Stacks actually is and what problem it is solving, but this is not a new problem. The Bitcoin write problem has been a bit of a holy grail problem in the crypto world for a while now. +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. -Bitcoin is the OG cryptocurrency and has the largest market cap, but it also some of the least functionality, which means if we want to make it a productive asset and use it to build a decentralized economy, we need to take a layered approach and let Bitcoin do what it does best, while creating additional layers on top of it to add functionality. +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. -So how does Stacks compare to some of the other approaches to layering on top of Bitcoin? +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 @@ -56,6 +80,32 @@ The Liquid consensus mechanism is managed by 15 functionaries, who handle the tr 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 follow Bitcoin finality with 100% Bitcoin hashpower. 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 designers of the Nakamoto release have decided to wait for 150 blocks before Bitcoin finality kicks in; this is mostly done to allow short-term forks to be resolved at the Stacks level. This design also means that most Maximal Extractable Value (MEV) action happens on the Stacks layer side and not on the Bitcoin side. There is always a fear of MEV incentives messing with Bitcoin mining, and the Stacks layer explicitly attracts most MEV activity to happen on the Stacks layer vs. Bitcoin L1 (the assumption here is that most MEV activity will occur within 150 blocks). Changing the variable from 150 to 6 blocks is trivial technically and can be configured as needed. Sovereign rollups effectively use a variable of 0 blocks and work similarly to the Stacks layer for reorg resistance. + +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. @@ -70,27 +120,18 @@ This is why networks like Lightning and other P2P networks don't need tokens, th 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. -But because it has its own execution environment and smart contract state to maintain, it needs a token to incentivize maintenance of the network. - -But it goes further than that. It is possible to build a system like this without a token using something like merge-mining or a sidechain, but then we lose out on the additional benefit of having the chain state's safety underpinned by its entire token economy's value. - -In the case of Stacks, the safety and liveness of the chain are underpinned by this value, and the stacking mechanism incentivizes network members to increase this value. - -From Jude Nelson, Stacks core developer: - -"How hard is it to cause a safety failure (i.e. a double-spend via a reorg) on just the canonical Stacks chain fork? Anyone can become a miner by spending BTC, so without loss of generality, reverting the last block on the canonical chain is at least as hard in expectation as spending more BTC than the rest of the miners combined for that block. Because each Bitcoin block selects at most one Stacks block, the act of reorging the canonical Stacks chain back N blocks is the act of winning at least N + 1 blocks built off of a common ancestor that is N blocks deep. This is a lower bound on the number of Bitcoin blocks mined during which a reorg needs to take place — in practice, honest miners will keep working on the canonical chain, and will win some Stacks blocks of their own, which in turn increases the number of Stacks blocks the reorging miners must win. - -How costly is it to carry out a reorg of N blocks? It’s a function of how valuable STX is relative to BTC — the more valuable STX are, the more BTC honest miners are committing to mining (this has borne out in practice), and thus the more BTC a reorging miner must commit. Therefore, the cost of a reorg is a function of the value of STX. +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. -This is similar to the economic security of a PoW blockchain. Like in PoW, each fork of the Stacks chain has its own independent “security budget” — an attacker must out-spend the security budget to carry out a reorg, and the security budget is a function of the block rewards. In PoX, the only difference is that the miners spend another blockchain’s tokens (BTC in Stacks’ case) instead of energy. Therefore, Stacks can’t be a sidechain, a drivechain, or a merge-mined chain, because none of these other systems’ security budgets are a function of their tokens’ worth. Sidechains, drivechains, and merged-mined chains all rely on external miners for their safety, since their safety is guaranteed in part by external miners validating their blocks. The onus on these systems is to get external miners to care enough to do so, and in the case of sidechains, drivechains, and blind merged-mined chains, there is an additional onus to encourage their nodes to mine blocks at all (since there is no on-chain reward for them to earn by doing so). By contrast, disinterested Bitcoin miners neither assist nor prevent a reorg in PoX — they only record the history of all Stacks forks. +The Stacks token (STX) is primarily meant to be used for two things (details in Stacks paper): -PoX offers two additional, unique security properties on top of PoW. First, no matter how much BTC a reorging miner can commit, the act of executing a reorg is going to be time-consuming. Unless the attacker can attack the Bitcoin chain itself by quickly producing a better Bitcoin fork, a reorging miner must sustain the attack for at least N + 1 Bitcoin blocks. This gives honest miners and users ample time to notice and react to the reorg attempt. +1. Incentives for Stacks L2 miners +2. Incentives for peg-out signers -Second, the history of block production in all Stacks forks is embedded within Bitcoin. This allows the system to leverage Bitcoin’s security budget in order to ensure that all forks are public. This is because the act of producing a hidden Stacks fork, where the fork’s block hashes are not known to the honest miners, is the act of producing a hidden canonical Bitcoin fork. Therefore, the act of producing a hidden Stacks fork is at least as hard as reorging the Bitcoin chain. A PoX chain leverages this property not to prevent reorgs, but to make reorgs unprofitable. +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. -By anchoring blocks to an existing blockchain, a PoX chain forces reorgs to happen out in the open, thereby giving advance warning to all honest network participants when they happen. Honest miners, users, and exchanges will see the PoX transactions for reorg attempts on the existing blockchain, and adapt their behaviors accordingly: honest miners will increase their commitments, and users and exchanges will require more confirmations for transactions. This makes the act of carrying out a reorg while also making a profit much more challenging, since malicious reorgs — like selfish mining and double-spending — rely on secrecy to work effectively. Specific to Stacks, miners are additionally required to mine for a “warm-up” period of two blocks, during which they must spend BTC at their target commit levels but will not win any Stacks blocks. So, a high-budget reorg attempt will not only be costly, but will also alert the rest of the network before the damage is done." +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. -- [What Kind of Blockchain is Stacks?](https://stacks.org/stacks-blockchain) +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 From 67da775ddefd80c7c333a4dd35a8c453ce26f00a Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Thu, 23 Mar 2023 21:29:40 +0100 Subject: [PATCH 0989/1444] New translations btc-connection.md (Korean) --- .../current/stacks-academy/btc-connection.md | 81 ++++++++++++++----- 1 file changed, 61 insertions(+), 20 deletions(-) diff --git a/i18n/ko/docusaurus-plugin-content-docs/current/stacks-academy/btc-connection.md b/i18n/ko/docusaurus-plugin-content-docs/current/stacks-academy/btc-connection.md index b4db915969..a3dd62f9ff 100644 --- a/i18n/ko/docusaurus-plugin-content-docs/current/stacks-academy/btc-connection.md +++ b/i18n/ko/docusaurus-plugin-content-docs/current/stacks-academy/btc-connection.md @@ -14,13 +14,37 @@ This topic is a bit of a rabbit hole, and this section of Stacks Academy is pret Let's get into it. -## Stacks Among Other Bitcoin Layers +## 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: -In the [last section](./what-is-stacks.md) we covered what Stacks actually is and what problem it is solving, but this is not a new problem. The Bitcoin write problem has been a bit of a holy grail problem in the crypto world for a while now. +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. -Bitcoin is the OG cryptocurrency and has the largest market cap, but it also some of the least functionality, which means if we want to make it a productive asset and use it to build a decentralized economy, we need to take a layered approach and let Bitcoin do what it does best, while creating additional layers on top of it to add functionality. +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. -So how does Stacks compare to some of the other approaches to layering on top of Bitcoin? +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 @@ -56,6 +80,32 @@ The Liquid consensus mechanism is managed by 15 functionaries, who handle the tr 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 follow Bitcoin finality with 100% Bitcoin hashpower. 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 designers of the Nakamoto release have decided to wait for 150 blocks before Bitcoin finality kicks in; this is mostly done to allow short-term forks to be resolved at the Stacks level. This design also means that most Maximal Extractable Value (MEV) action happens on the Stacks layer side and not on the Bitcoin side. There is always a fear of MEV incentives messing with Bitcoin mining, and the Stacks layer explicitly attracts most MEV activity to happen on the Stacks layer vs. Bitcoin L1 (the assumption here is that most MEV activity will occur within 150 blocks). Changing the variable from 150 to 6 blocks is trivial technically and can be configured as needed. Sovereign rollups effectively use a variable of 0 blocks and work similarly to the Stacks layer for reorg resistance. + +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. @@ -70,27 +120,18 @@ This is why networks like Lightning and other P2P networks don't need tokens, th 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. -But because it has its own execution environment and smart contract state to maintain, it needs a token to incentivize maintenance of the network. - -But it goes further than that. It is possible to build a system like this without a token using something like merge-mining or a sidechain, but then we lose out on the additional benefit of having the chain state's safety underpinned by its entire token economy's value. - -In the case of Stacks, the safety and liveness of the chain are underpinned by this value, and the stacking mechanism incentivizes network members to increase this value. - -From Jude Nelson, Stacks core developer: - -"How hard is it to cause a safety failure (i.e. a double-spend via a reorg) on just the canonical Stacks chain fork? Anyone can become a miner by spending BTC, so without loss of generality, reverting the last block on the canonical chain is at least as hard in expectation as spending more BTC than the rest of the miners combined for that block. Because each Bitcoin block selects at most one Stacks block, the act of reorging the canonical Stacks chain back N blocks is the act of winning at least N + 1 blocks built off of a common ancestor that is N blocks deep. This is a lower bound on the number of Bitcoin blocks mined during which a reorg needs to take place — in practice, honest miners will keep working on the canonical chain, and will win some Stacks blocks of their own, which in turn increases the number of Stacks blocks the reorging miners must win. - -How costly is it to carry out a reorg of N blocks? It’s a function of how valuable STX is relative to BTC — the more valuable STX are, the more BTC honest miners are committing to mining (this has borne out in practice), and thus the more BTC a reorging miner must commit. Therefore, the cost of a reorg is a function of the value of STX. +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. -This is similar to the economic security of a PoW blockchain. Like in PoW, each fork of the Stacks chain has its own independent “security budget” — an attacker must out-spend the security budget to carry out a reorg, and the security budget is a function of the block rewards. In PoX, the only difference is that the miners spend another blockchain’s tokens (BTC in Stacks’ case) instead of energy. Therefore, Stacks can’t be a sidechain, a drivechain, or a merge-mined chain, because none of these other systems’ security budgets are a function of their tokens’ worth. Sidechains, drivechains, and merged-mined chains all rely on external miners for their safety, since their safety is guaranteed in part by external miners validating their blocks. The onus on these systems is to get external miners to care enough to do so, and in the case of sidechains, drivechains, and blind merged-mined chains, there is an additional onus to encourage their nodes to mine blocks at all (since there is no on-chain reward for them to earn by doing so). By contrast, disinterested Bitcoin miners neither assist nor prevent a reorg in PoX — they only record the history of all Stacks forks. +The Stacks token (STX) is primarily meant to be used for two things (details in Stacks paper): -PoX offers two additional, unique security properties on top of PoW. First, no matter how much BTC a reorging miner can commit, the act of executing a reorg is going to be time-consuming. Unless the attacker can attack the Bitcoin chain itself by quickly producing a better Bitcoin fork, a reorging miner must sustain the attack for at least N + 1 Bitcoin blocks. This gives honest miners and users ample time to notice and react to the reorg attempt. +1. Incentives for Stacks L2 miners +2. Incentives for peg-out signers -Second, the history of block production in all Stacks forks is embedded within Bitcoin. This allows the system to leverage Bitcoin’s security budget in order to ensure that all forks are public. This is because the act of producing a hidden Stacks fork, where the fork’s block hashes are not known to the honest miners, is the act of producing a hidden canonical Bitcoin fork. Therefore, the act of producing a hidden Stacks fork is at least as hard as reorging the Bitcoin chain. A PoX chain leverages this property not to prevent reorgs, but to make reorgs unprofitable. +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. -By anchoring blocks to an existing blockchain, a PoX chain forces reorgs to happen out in the open, thereby giving advance warning to all honest network participants when they happen. Honest miners, users, and exchanges will see the PoX transactions for reorg attempts on the existing blockchain, and adapt their behaviors accordingly: honest miners will increase their commitments, and users and exchanges will require more confirmations for transactions. This makes the act of carrying out a reorg while also making a profit much more challenging, since malicious reorgs — like selfish mining and double-spending — rely on secrecy to work effectively. Specific to Stacks, miners are additionally required to mine for a “warm-up” period of two blocks, during which they must spend BTC at their target commit levels but will not win any Stacks blocks. So, a high-budget reorg attempt will not only be costly, but will also alert the rest of the network before the damage is done." +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. -- [What Kind of Blockchain is Stacks?](https://stacks.org/stacks-blockchain) +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 From 01480f8a4cc34b755ce258590a22d22c748b2887 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Thu, 23 Mar 2023 21:29:41 +0100 Subject: [PATCH 0990/1444] New translations btc-connection.md (Russian) --- .../current/stacks-academy/btc-connection.md | 81 ++++++++++++++----- 1 file changed, 61 insertions(+), 20 deletions(-) diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/stacks-academy/btc-connection.md b/i18n/ru/docusaurus-plugin-content-docs/current/stacks-academy/btc-connection.md index b4db915969..a3dd62f9ff 100644 --- a/i18n/ru/docusaurus-plugin-content-docs/current/stacks-academy/btc-connection.md +++ b/i18n/ru/docusaurus-plugin-content-docs/current/stacks-academy/btc-connection.md @@ -14,13 +14,37 @@ This topic is a bit of a rabbit hole, and this section of Stacks Academy is pret Let's get into it. -## Stacks Among Other Bitcoin Layers +## 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: -In the [last section](./what-is-stacks.md) we covered what Stacks actually is and what problem it is solving, but this is not a new problem. The Bitcoin write problem has been a bit of a holy grail problem in the crypto world for a while now. +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. -Bitcoin is the OG cryptocurrency and has the largest market cap, but it also some of the least functionality, which means if we want to make it a productive asset and use it to build a decentralized economy, we need to take a layered approach and let Bitcoin do what it does best, while creating additional layers on top of it to add functionality. +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. -So how does Stacks compare to some of the other approaches to layering on top of Bitcoin? +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 @@ -56,6 +80,32 @@ The Liquid consensus mechanism is managed by 15 functionaries, who handle the tr 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 follow Bitcoin finality with 100% Bitcoin hashpower. 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 designers of the Nakamoto release have decided to wait for 150 blocks before Bitcoin finality kicks in; this is mostly done to allow short-term forks to be resolved at the Stacks level. This design also means that most Maximal Extractable Value (MEV) action happens on the Stacks layer side and not on the Bitcoin side. There is always a fear of MEV incentives messing with Bitcoin mining, and the Stacks layer explicitly attracts most MEV activity to happen on the Stacks layer vs. Bitcoin L1 (the assumption here is that most MEV activity will occur within 150 blocks). Changing the variable from 150 to 6 blocks is trivial technically and can be configured as needed. Sovereign rollups effectively use a variable of 0 blocks and work similarly to the Stacks layer for reorg resistance. + +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. @@ -70,27 +120,18 @@ This is why networks like Lightning and other P2P networks don't need tokens, th 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. -But because it has its own execution environment and smart contract state to maintain, it needs a token to incentivize maintenance of the network. - -But it goes further than that. It is possible to build a system like this without a token using something like merge-mining or a sidechain, but then we lose out on the additional benefit of having the chain state's safety underpinned by its entire token economy's value. - -In the case of Stacks, the safety and liveness of the chain are underpinned by this value, and the stacking mechanism incentivizes network members to increase this value. - -From Jude Nelson, Stacks core developer: - -"How hard is it to cause a safety failure (i.e. a double-spend via a reorg) on just the canonical Stacks chain fork? Anyone can become a miner by spending BTC, so without loss of generality, reverting the last block on the canonical chain is at least as hard in expectation as spending more BTC than the rest of the miners combined for that block. Because each Bitcoin block selects at most one Stacks block, the act of reorging the canonical Stacks chain back N blocks is the act of winning at least N + 1 blocks built off of a common ancestor that is N blocks deep. This is a lower bound on the number of Bitcoin blocks mined during which a reorg needs to take place — in practice, honest miners will keep working on the canonical chain, and will win some Stacks blocks of their own, which in turn increases the number of Stacks blocks the reorging miners must win. - -How costly is it to carry out a reorg of N blocks? It’s a function of how valuable STX is relative to BTC — the more valuable STX are, the more BTC honest miners are committing to mining (this has borne out in practice), and thus the more BTC a reorging miner must commit. Therefore, the cost of a reorg is a function of the value of STX. +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. -This is similar to the economic security of a PoW blockchain. Like in PoW, each fork of the Stacks chain has its own independent “security budget” — an attacker must out-spend the security budget to carry out a reorg, and the security budget is a function of the block rewards. In PoX, the only difference is that the miners spend another blockchain’s tokens (BTC in Stacks’ case) instead of energy. Therefore, Stacks can’t be a sidechain, a drivechain, or a merge-mined chain, because none of these other systems’ security budgets are a function of their tokens’ worth. Sidechains, drivechains, and merged-mined chains all rely on external miners for their safety, since their safety is guaranteed in part by external miners validating their blocks. The onus on these systems is to get external miners to care enough to do so, and in the case of sidechains, drivechains, and blind merged-mined chains, there is an additional onus to encourage their nodes to mine blocks at all (since there is no on-chain reward for them to earn by doing so). By contrast, disinterested Bitcoin miners neither assist nor prevent a reorg in PoX — they only record the history of all Stacks forks. +The Stacks token (STX) is primarily meant to be used for two things (details in Stacks paper): -PoX offers two additional, unique security properties on top of PoW. First, no matter how much BTC a reorging miner can commit, the act of executing a reorg is going to be time-consuming. Unless the attacker can attack the Bitcoin chain itself by quickly producing a better Bitcoin fork, a reorging miner must sustain the attack for at least N + 1 Bitcoin blocks. This gives honest miners and users ample time to notice and react to the reorg attempt. +1. Incentives for Stacks L2 miners +2. Incentives for peg-out signers -Second, the history of block production in all Stacks forks is embedded within Bitcoin. This allows the system to leverage Bitcoin’s security budget in order to ensure that all forks are public. This is because the act of producing a hidden Stacks fork, where the fork’s block hashes are not known to the honest miners, is the act of producing a hidden canonical Bitcoin fork. Therefore, the act of producing a hidden Stacks fork is at least as hard as reorging the Bitcoin chain. A PoX chain leverages this property not to prevent reorgs, but to make reorgs unprofitable. +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. -By anchoring blocks to an existing blockchain, a PoX chain forces reorgs to happen out in the open, thereby giving advance warning to all honest network participants when they happen. Honest miners, users, and exchanges will see the PoX transactions for reorg attempts on the existing blockchain, and adapt their behaviors accordingly: honest miners will increase their commitments, and users and exchanges will require more confirmations for transactions. This makes the act of carrying out a reorg while also making a profit much more challenging, since malicious reorgs — like selfish mining and double-spending — rely on secrecy to work effectively. Specific to Stacks, miners are additionally required to mine for a “warm-up” period of two blocks, during which they must spend BTC at their target commit levels but will not win any Stacks blocks. So, a high-budget reorg attempt will not only be costly, but will also alert the rest of the network before the damage is done." +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. -- [What Kind of Blockchain is Stacks?](https://stacks.org/stacks-blockchain) +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 From a959b1cfea28fca6ef5c821d788bf93e9123d6eb Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Thu, 23 Mar 2023 21:29:42 +0100 Subject: [PATCH 0991/1444] New translations btc-connection.md (Turkish) --- .../current/stacks-academy/btc-connection.md | 81 ++++++++++++++----- 1 file changed, 61 insertions(+), 20 deletions(-) diff --git a/i18n/tr/docusaurus-plugin-content-docs/current/stacks-academy/btc-connection.md b/i18n/tr/docusaurus-plugin-content-docs/current/stacks-academy/btc-connection.md index b4db915969..a3dd62f9ff 100644 --- a/i18n/tr/docusaurus-plugin-content-docs/current/stacks-academy/btc-connection.md +++ b/i18n/tr/docusaurus-plugin-content-docs/current/stacks-academy/btc-connection.md @@ -14,13 +14,37 @@ This topic is a bit of a rabbit hole, and this section of Stacks Academy is pret Let's get into it. -## Stacks Among Other Bitcoin Layers +## 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: -In the [last section](./what-is-stacks.md) we covered what Stacks actually is and what problem it is solving, but this is not a new problem. The Bitcoin write problem has been a bit of a holy grail problem in the crypto world for a while now. +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. -Bitcoin is the OG cryptocurrency and has the largest market cap, but it also some of the least functionality, which means if we want to make it a productive asset and use it to build a decentralized economy, we need to take a layered approach and let Bitcoin do what it does best, while creating additional layers on top of it to add functionality. +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. -So how does Stacks compare to some of the other approaches to layering on top of Bitcoin? +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 @@ -56,6 +80,32 @@ The Liquid consensus mechanism is managed by 15 functionaries, who handle the tr 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 follow Bitcoin finality with 100% Bitcoin hashpower. 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 designers of the Nakamoto release have decided to wait for 150 blocks before Bitcoin finality kicks in; this is mostly done to allow short-term forks to be resolved at the Stacks level. This design also means that most Maximal Extractable Value (MEV) action happens on the Stacks layer side and not on the Bitcoin side. There is always a fear of MEV incentives messing with Bitcoin mining, and the Stacks layer explicitly attracts most MEV activity to happen on the Stacks layer vs. Bitcoin L1 (the assumption here is that most MEV activity will occur within 150 blocks). Changing the variable from 150 to 6 blocks is trivial technically and can be configured as needed. Sovereign rollups effectively use a variable of 0 blocks and work similarly to the Stacks layer for reorg resistance. + +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. @@ -70,27 +120,18 @@ This is why networks like Lightning and other P2P networks don't need tokens, th 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. -But because it has its own execution environment and smart contract state to maintain, it needs a token to incentivize maintenance of the network. - -But it goes further than that. It is possible to build a system like this without a token using something like merge-mining or a sidechain, but then we lose out on the additional benefit of having the chain state's safety underpinned by its entire token economy's value. - -In the case of Stacks, the safety and liveness of the chain are underpinned by this value, and the stacking mechanism incentivizes network members to increase this value. - -From Jude Nelson, Stacks core developer: - -"How hard is it to cause a safety failure (i.e. a double-spend via a reorg) on just the canonical Stacks chain fork? Anyone can become a miner by spending BTC, so without loss of generality, reverting the last block on the canonical chain is at least as hard in expectation as spending more BTC than the rest of the miners combined for that block. Because each Bitcoin block selects at most one Stacks block, the act of reorging the canonical Stacks chain back N blocks is the act of winning at least N + 1 blocks built off of a common ancestor that is N blocks deep. This is a lower bound on the number of Bitcoin blocks mined during which a reorg needs to take place — in practice, honest miners will keep working on the canonical chain, and will win some Stacks blocks of their own, which in turn increases the number of Stacks blocks the reorging miners must win. - -How costly is it to carry out a reorg of N blocks? It’s a function of how valuable STX is relative to BTC — the more valuable STX are, the more BTC honest miners are committing to mining (this has borne out in practice), and thus the more BTC a reorging miner must commit. Therefore, the cost of a reorg is a function of the value of STX. +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. -This is similar to the economic security of a PoW blockchain. Like in PoW, each fork of the Stacks chain has its own independent “security budget” — an attacker must out-spend the security budget to carry out a reorg, and the security budget is a function of the block rewards. In PoX, the only difference is that the miners spend another blockchain’s tokens (BTC in Stacks’ case) instead of energy. Therefore, Stacks can’t be a sidechain, a drivechain, or a merge-mined chain, because none of these other systems’ security budgets are a function of their tokens’ worth. Sidechains, drivechains, and merged-mined chains all rely on external miners for their safety, since their safety is guaranteed in part by external miners validating their blocks. The onus on these systems is to get external miners to care enough to do so, and in the case of sidechains, drivechains, and blind merged-mined chains, there is an additional onus to encourage their nodes to mine blocks at all (since there is no on-chain reward for them to earn by doing so). By contrast, disinterested Bitcoin miners neither assist nor prevent a reorg in PoX — they only record the history of all Stacks forks. +The Stacks token (STX) is primarily meant to be used for two things (details in Stacks paper): -PoX offers two additional, unique security properties on top of PoW. First, no matter how much BTC a reorging miner can commit, the act of executing a reorg is going to be time-consuming. Unless the attacker can attack the Bitcoin chain itself by quickly producing a better Bitcoin fork, a reorging miner must sustain the attack for at least N + 1 Bitcoin blocks. This gives honest miners and users ample time to notice and react to the reorg attempt. +1. Incentives for Stacks L2 miners +2. Incentives for peg-out signers -Second, the history of block production in all Stacks forks is embedded within Bitcoin. This allows the system to leverage Bitcoin’s security budget in order to ensure that all forks are public. This is because the act of producing a hidden Stacks fork, where the fork’s block hashes are not known to the honest miners, is the act of producing a hidden canonical Bitcoin fork. Therefore, the act of producing a hidden Stacks fork is at least as hard as reorging the Bitcoin chain. A PoX chain leverages this property not to prevent reorgs, but to make reorgs unprofitable. +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. -By anchoring blocks to an existing blockchain, a PoX chain forces reorgs to happen out in the open, thereby giving advance warning to all honest network participants when they happen. Honest miners, users, and exchanges will see the PoX transactions for reorg attempts on the existing blockchain, and adapt their behaviors accordingly: honest miners will increase their commitments, and users and exchanges will require more confirmations for transactions. This makes the act of carrying out a reorg while also making a profit much more challenging, since malicious reorgs — like selfish mining and double-spending — rely on secrecy to work effectively. Specific to Stacks, miners are additionally required to mine for a “warm-up” period of two blocks, during which they must spend BTC at their target commit levels but will not win any Stacks blocks. So, a high-budget reorg attempt will not only be costly, but will also alert the rest of the network before the damage is done." +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. -- [What Kind of Blockchain is Stacks?](https://stacks.org/stacks-blockchain) +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 From c58da1d35897ab2e238d296805f1f066490d61a5 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Thu, 23 Mar 2023 21:29:43 +0100 Subject: [PATCH 0992/1444] New translations btc-connection.md (Chinese Simplified) --- .../current/stacks-academy/btc-connection.md | 81 ++++++++++++++----- 1 file changed, 61 insertions(+), 20 deletions(-) diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/stacks-academy/btc-connection.md b/i18n/zh/docusaurus-plugin-content-docs/current/stacks-academy/btc-connection.md index b4db915969..a3dd62f9ff 100644 --- a/i18n/zh/docusaurus-plugin-content-docs/current/stacks-academy/btc-connection.md +++ b/i18n/zh/docusaurus-plugin-content-docs/current/stacks-academy/btc-connection.md @@ -14,13 +14,37 @@ This topic is a bit of a rabbit hole, and this section of Stacks Academy is pret Let's get into it. -## Stacks Among Other Bitcoin Layers +## 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: -In the [last section](./what-is-stacks.md) we covered what Stacks actually is and what problem it is solving, but this is not a new problem. The Bitcoin write problem has been a bit of a holy grail problem in the crypto world for a while now. +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. -Bitcoin is the OG cryptocurrency and has the largest market cap, but it also some of the least functionality, which means if we want to make it a productive asset and use it to build a decentralized economy, we need to take a layered approach and let Bitcoin do what it does best, while creating additional layers on top of it to add functionality. +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. -So how does Stacks compare to some of the other approaches to layering on top of Bitcoin? +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 @@ -56,6 +80,32 @@ The Liquid consensus mechanism is managed by 15 functionaries, who handle the tr 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 follow Bitcoin finality with 100% Bitcoin hashpower. 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 designers of the Nakamoto release have decided to wait for 150 blocks before Bitcoin finality kicks in; this is mostly done to allow short-term forks to be resolved at the Stacks level. This design also means that most Maximal Extractable Value (MEV) action happens on the Stacks layer side and not on the Bitcoin side. There is always a fear of MEV incentives messing with Bitcoin mining, and the Stacks layer explicitly attracts most MEV activity to happen on the Stacks layer vs. Bitcoin L1 (the assumption here is that most MEV activity will occur within 150 blocks). Changing the variable from 150 to 6 blocks is trivial technically and can be configured as needed. Sovereign rollups effectively use a variable of 0 blocks and work similarly to the Stacks layer for reorg resistance. + +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. @@ -70,27 +120,18 @@ This is why networks like Lightning and other P2P networks don't need tokens, th 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. -But because it has its own execution environment and smart contract state to maintain, it needs a token to incentivize maintenance of the network. - -But it goes further than that. It is possible to build a system like this without a token using something like merge-mining or a sidechain, but then we lose out on the additional benefit of having the chain state's safety underpinned by its entire token economy's value. - -In the case of Stacks, the safety and liveness of the chain are underpinned by this value, and the stacking mechanism incentivizes network members to increase this value. - -From Jude Nelson, Stacks core developer: - -"How hard is it to cause a safety failure (i.e. a double-spend via a reorg) on just the canonical Stacks chain fork? Anyone can become a miner by spending BTC, so without loss of generality, reverting the last block on the canonical chain is at least as hard in expectation as spending more BTC than the rest of the miners combined for that block. Because each Bitcoin block selects at most one Stacks block, the act of reorging the canonical Stacks chain back N blocks is the act of winning at least N + 1 blocks built off of a common ancestor that is N blocks deep. This is a lower bound on the number of Bitcoin blocks mined during which a reorg needs to take place — in practice, honest miners will keep working on the canonical chain, and will win some Stacks blocks of their own, which in turn increases the number of Stacks blocks the reorging miners must win. - -How costly is it to carry out a reorg of N blocks? It’s a function of how valuable STX is relative to BTC — the more valuable STX are, the more BTC honest miners are committing to mining (this has borne out in practice), and thus the more BTC a reorging miner must commit. Therefore, the cost of a reorg is a function of the value of STX. +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. -This is similar to the economic security of a PoW blockchain. Like in PoW, each fork of the Stacks chain has its own independent “security budget” — an attacker must out-spend the security budget to carry out a reorg, and the security budget is a function of the block rewards. In PoX, the only difference is that the miners spend another blockchain’s tokens (BTC in Stacks’ case) instead of energy. Therefore, Stacks can’t be a sidechain, a drivechain, or a merge-mined chain, because none of these other systems’ security budgets are a function of their tokens’ worth. Sidechains, drivechains, and merged-mined chains all rely on external miners for their safety, since their safety is guaranteed in part by external miners validating their blocks. The onus on these systems is to get external miners to care enough to do so, and in the case of sidechains, drivechains, and blind merged-mined chains, there is an additional onus to encourage their nodes to mine blocks at all (since there is no on-chain reward for them to earn by doing so). By contrast, disinterested Bitcoin miners neither assist nor prevent a reorg in PoX — they only record the history of all Stacks forks. +The Stacks token (STX) is primarily meant to be used for two things (details in Stacks paper): -PoX offers two additional, unique security properties on top of PoW. First, no matter how much BTC a reorging miner can commit, the act of executing a reorg is going to be time-consuming. Unless the attacker can attack the Bitcoin chain itself by quickly producing a better Bitcoin fork, a reorging miner must sustain the attack for at least N + 1 Bitcoin blocks. This gives honest miners and users ample time to notice and react to the reorg attempt. +1. Incentives for Stacks L2 miners +2. Incentives for peg-out signers -Second, the history of block production in all Stacks forks is embedded within Bitcoin. This allows the system to leverage Bitcoin’s security budget in order to ensure that all forks are public. This is because the act of producing a hidden Stacks fork, where the fork’s block hashes are not known to the honest miners, is the act of producing a hidden canonical Bitcoin fork. Therefore, the act of producing a hidden Stacks fork is at least as hard as reorging the Bitcoin chain. A PoX chain leverages this property not to prevent reorgs, but to make reorgs unprofitable. +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. -By anchoring blocks to an existing blockchain, a PoX chain forces reorgs to happen out in the open, thereby giving advance warning to all honest network participants when they happen. Honest miners, users, and exchanges will see the PoX transactions for reorg attempts on the existing blockchain, and adapt their behaviors accordingly: honest miners will increase their commitments, and users and exchanges will require more confirmations for transactions. This makes the act of carrying out a reorg while also making a profit much more challenging, since malicious reorgs — like selfish mining and double-spending — rely on secrecy to work effectively. Specific to Stacks, miners are additionally required to mine for a “warm-up” period of two blocks, during which they must spend BTC at their target commit levels but will not win any Stacks blocks. So, a high-budget reorg attempt will not only be costly, but will also alert the rest of the network before the damage is done." +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. -- [What Kind of Blockchain is Stacks?](https://stacks.org/stacks-blockchain) +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 From 406770145af3def0e620d7391d875bd5b47fdcb0 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Thu, 23 Mar 2023 21:29:44 +0100 Subject: [PATCH 0993/1444] New translations btc-connection.md (Vietnamese) --- .../current/stacks-academy/btc-connection.md | 81 ++++++++++++++----- 1 file changed, 61 insertions(+), 20 deletions(-) diff --git a/i18n/vi/docusaurus-plugin-content-docs/current/stacks-academy/btc-connection.md b/i18n/vi/docusaurus-plugin-content-docs/current/stacks-academy/btc-connection.md index b4db915969..a3dd62f9ff 100644 --- a/i18n/vi/docusaurus-plugin-content-docs/current/stacks-academy/btc-connection.md +++ b/i18n/vi/docusaurus-plugin-content-docs/current/stacks-academy/btc-connection.md @@ -14,13 +14,37 @@ This topic is a bit of a rabbit hole, and this section of Stacks Academy is pret Let's get into it. -## Stacks Among Other Bitcoin Layers +## 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: -In the [last section](./what-is-stacks.md) we covered what Stacks actually is and what problem it is solving, but this is not a new problem. The Bitcoin write problem has been a bit of a holy grail problem in the crypto world for a while now. +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. -Bitcoin is the OG cryptocurrency and has the largest market cap, but it also some of the least functionality, which means if we want to make it a productive asset and use it to build a decentralized economy, we need to take a layered approach and let Bitcoin do what it does best, while creating additional layers on top of it to add functionality. +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. -So how does Stacks compare to some of the other approaches to layering on top of Bitcoin? +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 @@ -56,6 +80,32 @@ The Liquid consensus mechanism is managed by 15 functionaries, who handle the tr 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 follow Bitcoin finality with 100% Bitcoin hashpower. 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 designers of the Nakamoto release have decided to wait for 150 blocks before Bitcoin finality kicks in; this is mostly done to allow short-term forks to be resolved at the Stacks level. This design also means that most Maximal Extractable Value (MEV) action happens on the Stacks layer side and not on the Bitcoin side. There is always a fear of MEV incentives messing with Bitcoin mining, and the Stacks layer explicitly attracts most MEV activity to happen on the Stacks layer vs. Bitcoin L1 (the assumption here is that most MEV activity will occur within 150 blocks). Changing the variable from 150 to 6 blocks is trivial technically and can be configured as needed. Sovereign rollups effectively use a variable of 0 blocks and work similarly to the Stacks layer for reorg resistance. + +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. @@ -70,27 +120,18 @@ This is why networks like Lightning and other P2P networks don't need tokens, th 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. -But because it has its own execution environment and smart contract state to maintain, it needs a token to incentivize maintenance of the network. - -But it goes further than that. It is possible to build a system like this without a token using something like merge-mining or a sidechain, but then we lose out on the additional benefit of having the chain state's safety underpinned by its entire token economy's value. - -In the case of Stacks, the safety and liveness of the chain are underpinned by this value, and the stacking mechanism incentivizes network members to increase this value. - -From Jude Nelson, Stacks core developer: - -"How hard is it to cause a safety failure (i.e. a double-spend via a reorg) on just the canonical Stacks chain fork? Anyone can become a miner by spending BTC, so without loss of generality, reverting the last block on the canonical chain is at least as hard in expectation as spending more BTC than the rest of the miners combined for that block. Because each Bitcoin block selects at most one Stacks block, the act of reorging the canonical Stacks chain back N blocks is the act of winning at least N + 1 blocks built off of a common ancestor that is N blocks deep. This is a lower bound on the number of Bitcoin blocks mined during which a reorg needs to take place — in practice, honest miners will keep working on the canonical chain, and will win some Stacks blocks of their own, which in turn increases the number of Stacks blocks the reorging miners must win. - -How costly is it to carry out a reorg of N blocks? It’s a function of how valuable STX is relative to BTC — the more valuable STX are, the more BTC honest miners are committing to mining (this has borne out in practice), and thus the more BTC a reorging miner must commit. Therefore, the cost of a reorg is a function of the value of STX. +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. -This is similar to the economic security of a PoW blockchain. Like in PoW, each fork of the Stacks chain has its own independent “security budget” — an attacker must out-spend the security budget to carry out a reorg, and the security budget is a function of the block rewards. In PoX, the only difference is that the miners spend another blockchain’s tokens (BTC in Stacks’ case) instead of energy. Therefore, Stacks can’t be a sidechain, a drivechain, or a merge-mined chain, because none of these other systems’ security budgets are a function of their tokens’ worth. Sidechains, drivechains, and merged-mined chains all rely on external miners for their safety, since their safety is guaranteed in part by external miners validating their blocks. The onus on these systems is to get external miners to care enough to do so, and in the case of sidechains, drivechains, and blind merged-mined chains, there is an additional onus to encourage their nodes to mine blocks at all (since there is no on-chain reward for them to earn by doing so). By contrast, disinterested Bitcoin miners neither assist nor prevent a reorg in PoX — they only record the history of all Stacks forks. +The Stacks token (STX) is primarily meant to be used for two things (details in Stacks paper): -PoX offers two additional, unique security properties on top of PoW. First, no matter how much BTC a reorging miner can commit, the act of executing a reorg is going to be time-consuming. Unless the attacker can attack the Bitcoin chain itself by quickly producing a better Bitcoin fork, a reorging miner must sustain the attack for at least N + 1 Bitcoin blocks. This gives honest miners and users ample time to notice and react to the reorg attempt. +1. Incentives for Stacks L2 miners +2. Incentives for peg-out signers -Second, the history of block production in all Stacks forks is embedded within Bitcoin. This allows the system to leverage Bitcoin’s security budget in order to ensure that all forks are public. This is because the act of producing a hidden Stacks fork, where the fork’s block hashes are not known to the honest miners, is the act of producing a hidden canonical Bitcoin fork. Therefore, the act of producing a hidden Stacks fork is at least as hard as reorging the Bitcoin chain. A PoX chain leverages this property not to prevent reorgs, but to make reorgs unprofitable. +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. -By anchoring blocks to an existing blockchain, a PoX chain forces reorgs to happen out in the open, thereby giving advance warning to all honest network participants when they happen. Honest miners, users, and exchanges will see the PoX transactions for reorg attempts on the existing blockchain, and adapt their behaviors accordingly: honest miners will increase their commitments, and users and exchanges will require more confirmations for transactions. This makes the act of carrying out a reorg while also making a profit much more challenging, since malicious reorgs — like selfish mining and double-spending — rely on secrecy to work effectively. Specific to Stacks, miners are additionally required to mine for a “warm-up” period of two blocks, during which they must spend BTC at their target commit levels but will not win any Stacks blocks. So, a high-budget reorg attempt will not only be costly, but will also alert the rest of the network before the damage is done." +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. -- [What Kind of Blockchain is Stacks?](https://stacks.org/stacks-blockchain) +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 From 8dfac016b3daa665792da3719d8a58e8fa7e5723 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Thu, 23 Mar 2023 21:29:46 +0100 Subject: [PATCH 0994/1444] New translations btc-connection.md (Portuguese, Brazilian) --- .../current/stacks-academy/btc-connection.md | 81 ++++++++++++++----- 1 file changed, 61 insertions(+), 20 deletions(-) diff --git a/i18n/pt/docusaurus-plugin-content-docs/current/stacks-academy/btc-connection.md b/i18n/pt/docusaurus-plugin-content-docs/current/stacks-academy/btc-connection.md index b4db915969..a3dd62f9ff 100644 --- a/i18n/pt/docusaurus-plugin-content-docs/current/stacks-academy/btc-connection.md +++ b/i18n/pt/docusaurus-plugin-content-docs/current/stacks-academy/btc-connection.md @@ -14,13 +14,37 @@ This topic is a bit of a rabbit hole, and this section of Stacks Academy is pret Let's get into it. -## Stacks Among Other Bitcoin Layers +## 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: -In the [last section](./what-is-stacks.md) we covered what Stacks actually is and what problem it is solving, but this is not a new problem. The Bitcoin write problem has been a bit of a holy grail problem in the crypto world for a while now. +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. -Bitcoin is the OG cryptocurrency and has the largest market cap, but it also some of the least functionality, which means if we want to make it a productive asset and use it to build a decentralized economy, we need to take a layered approach and let Bitcoin do what it does best, while creating additional layers on top of it to add functionality. +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. -So how does Stacks compare to some of the other approaches to layering on top of Bitcoin? +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 @@ -56,6 +80,32 @@ The Liquid consensus mechanism is managed by 15 functionaries, who handle the tr 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 follow Bitcoin finality with 100% Bitcoin hashpower. 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 designers of the Nakamoto release have decided to wait for 150 blocks before Bitcoin finality kicks in; this is mostly done to allow short-term forks to be resolved at the Stacks level. This design also means that most Maximal Extractable Value (MEV) action happens on the Stacks layer side and not on the Bitcoin side. There is always a fear of MEV incentives messing with Bitcoin mining, and the Stacks layer explicitly attracts most MEV activity to happen on the Stacks layer vs. Bitcoin L1 (the assumption here is that most MEV activity will occur within 150 blocks). Changing the variable from 150 to 6 blocks is trivial technically and can be configured as needed. Sovereign rollups effectively use a variable of 0 blocks and work similarly to the Stacks layer for reorg resistance. + +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. @@ -70,27 +120,18 @@ This is why networks like Lightning and other P2P networks don't need tokens, th 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. -But because it has its own execution environment and smart contract state to maintain, it needs a token to incentivize maintenance of the network. - -But it goes further than that. It is possible to build a system like this without a token using something like merge-mining or a sidechain, but then we lose out on the additional benefit of having the chain state's safety underpinned by its entire token economy's value. - -In the case of Stacks, the safety and liveness of the chain are underpinned by this value, and the stacking mechanism incentivizes network members to increase this value. - -From Jude Nelson, Stacks core developer: - -"How hard is it to cause a safety failure (i.e. a double-spend via a reorg) on just the canonical Stacks chain fork? Anyone can become a miner by spending BTC, so without loss of generality, reverting the last block on the canonical chain is at least as hard in expectation as spending more BTC than the rest of the miners combined for that block. Because each Bitcoin block selects at most one Stacks block, the act of reorging the canonical Stacks chain back N blocks is the act of winning at least N + 1 blocks built off of a common ancestor that is N blocks deep. This is a lower bound on the number of Bitcoin blocks mined during which a reorg needs to take place — in practice, honest miners will keep working on the canonical chain, and will win some Stacks blocks of their own, which in turn increases the number of Stacks blocks the reorging miners must win. - -How costly is it to carry out a reorg of N blocks? It’s a function of how valuable STX is relative to BTC — the more valuable STX are, the more BTC honest miners are committing to mining (this has borne out in practice), and thus the more BTC a reorging miner must commit. Therefore, the cost of a reorg is a function of the value of STX. +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. -This is similar to the economic security of a PoW blockchain. Like in PoW, each fork of the Stacks chain has its own independent “security budget” — an attacker must out-spend the security budget to carry out a reorg, and the security budget is a function of the block rewards. In PoX, the only difference is that the miners spend another blockchain’s tokens (BTC in Stacks’ case) instead of energy. Therefore, Stacks can’t be a sidechain, a drivechain, or a merge-mined chain, because none of these other systems’ security budgets are a function of their tokens’ worth. Sidechains, drivechains, and merged-mined chains all rely on external miners for their safety, since their safety is guaranteed in part by external miners validating their blocks. The onus on these systems is to get external miners to care enough to do so, and in the case of sidechains, drivechains, and blind merged-mined chains, there is an additional onus to encourage their nodes to mine blocks at all (since there is no on-chain reward for them to earn by doing so). By contrast, disinterested Bitcoin miners neither assist nor prevent a reorg in PoX — they only record the history of all Stacks forks. +The Stacks token (STX) is primarily meant to be used for two things (details in Stacks paper): -PoX offers two additional, unique security properties on top of PoW. First, no matter how much BTC a reorging miner can commit, the act of executing a reorg is going to be time-consuming. Unless the attacker can attack the Bitcoin chain itself by quickly producing a better Bitcoin fork, a reorging miner must sustain the attack for at least N + 1 Bitcoin blocks. This gives honest miners and users ample time to notice and react to the reorg attempt. +1. Incentives for Stacks L2 miners +2. Incentives for peg-out signers -Second, the history of block production in all Stacks forks is embedded within Bitcoin. This allows the system to leverage Bitcoin’s security budget in order to ensure that all forks are public. This is because the act of producing a hidden Stacks fork, where the fork’s block hashes are not known to the honest miners, is the act of producing a hidden canonical Bitcoin fork. Therefore, the act of producing a hidden Stacks fork is at least as hard as reorging the Bitcoin chain. A PoX chain leverages this property not to prevent reorgs, but to make reorgs unprofitable. +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. -By anchoring blocks to an existing blockchain, a PoX chain forces reorgs to happen out in the open, thereby giving advance warning to all honest network participants when they happen. Honest miners, users, and exchanges will see the PoX transactions for reorg attempts on the existing blockchain, and adapt their behaviors accordingly: honest miners will increase their commitments, and users and exchanges will require more confirmations for transactions. This makes the act of carrying out a reorg while also making a profit much more challenging, since malicious reorgs — like selfish mining and double-spending — rely on secrecy to work effectively. Specific to Stacks, miners are additionally required to mine for a “warm-up” period of two blocks, during which they must spend BTC at their target commit levels but will not win any Stacks blocks. So, a high-budget reorg attempt will not only be costly, but will also alert the rest of the network before the damage is done." +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. -- [What Kind of Blockchain is Stacks?](https://stacks.org/stacks-blockchain) +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 From a49279caceea2239ed08987d4064ba728b47f5cd Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Thu, 23 Mar 2023 21:29:47 +0100 Subject: [PATCH 0995/1444] New translations btc-connection.md (Indonesian) --- .../current/stacks-academy/btc-connection.md | 81 ++++++++++++++----- 1 file changed, 61 insertions(+), 20 deletions(-) diff --git a/i18n/id/docusaurus-plugin-content-docs/current/stacks-academy/btc-connection.md b/i18n/id/docusaurus-plugin-content-docs/current/stacks-academy/btc-connection.md index b4db915969..a3dd62f9ff 100644 --- a/i18n/id/docusaurus-plugin-content-docs/current/stacks-academy/btc-connection.md +++ b/i18n/id/docusaurus-plugin-content-docs/current/stacks-academy/btc-connection.md @@ -14,13 +14,37 @@ This topic is a bit of a rabbit hole, and this section of Stacks Academy is pret Let's get into it. -## Stacks Among Other Bitcoin Layers +## 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: -In the [last section](./what-is-stacks.md) we covered what Stacks actually is and what problem it is solving, but this is not a new problem. The Bitcoin write problem has been a bit of a holy grail problem in the crypto world for a while now. +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. -Bitcoin is the OG cryptocurrency and has the largest market cap, but it also some of the least functionality, which means if we want to make it a productive asset and use it to build a decentralized economy, we need to take a layered approach and let Bitcoin do what it does best, while creating additional layers on top of it to add functionality. +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. -So how does Stacks compare to some of the other approaches to layering on top of Bitcoin? +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 @@ -56,6 +80,32 @@ The Liquid consensus mechanism is managed by 15 functionaries, who handle the tr 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 follow Bitcoin finality with 100% Bitcoin hashpower. 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 designers of the Nakamoto release have decided to wait for 150 blocks before Bitcoin finality kicks in; this is mostly done to allow short-term forks to be resolved at the Stacks level. This design also means that most Maximal Extractable Value (MEV) action happens on the Stacks layer side and not on the Bitcoin side. There is always a fear of MEV incentives messing with Bitcoin mining, and the Stacks layer explicitly attracts most MEV activity to happen on the Stacks layer vs. Bitcoin L1 (the assumption here is that most MEV activity will occur within 150 blocks). Changing the variable from 150 to 6 blocks is trivial technically and can be configured as needed. Sovereign rollups effectively use a variable of 0 blocks and work similarly to the Stacks layer for reorg resistance. + +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. @@ -70,27 +120,18 @@ This is why networks like Lightning and other P2P networks don't need tokens, th 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. -But because it has its own execution environment and smart contract state to maintain, it needs a token to incentivize maintenance of the network. - -But it goes further than that. It is possible to build a system like this without a token using something like merge-mining or a sidechain, but then we lose out on the additional benefit of having the chain state's safety underpinned by its entire token economy's value. - -In the case of Stacks, the safety and liveness of the chain are underpinned by this value, and the stacking mechanism incentivizes network members to increase this value. - -From Jude Nelson, Stacks core developer: - -"How hard is it to cause a safety failure (i.e. a double-spend via a reorg) on just the canonical Stacks chain fork? Anyone can become a miner by spending BTC, so without loss of generality, reverting the last block on the canonical chain is at least as hard in expectation as spending more BTC than the rest of the miners combined for that block. Because each Bitcoin block selects at most one Stacks block, the act of reorging the canonical Stacks chain back N blocks is the act of winning at least N + 1 blocks built off of a common ancestor that is N blocks deep. This is a lower bound on the number of Bitcoin blocks mined during which a reorg needs to take place — in practice, honest miners will keep working on the canonical chain, and will win some Stacks blocks of their own, which in turn increases the number of Stacks blocks the reorging miners must win. - -How costly is it to carry out a reorg of N blocks? It’s a function of how valuable STX is relative to BTC — the more valuable STX are, the more BTC honest miners are committing to mining (this has borne out in practice), and thus the more BTC a reorging miner must commit. Therefore, the cost of a reorg is a function of the value of STX. +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. -This is similar to the economic security of a PoW blockchain. Like in PoW, each fork of the Stacks chain has its own independent “security budget” — an attacker must out-spend the security budget to carry out a reorg, and the security budget is a function of the block rewards. In PoX, the only difference is that the miners spend another blockchain’s tokens (BTC in Stacks’ case) instead of energy. Therefore, Stacks can’t be a sidechain, a drivechain, or a merge-mined chain, because none of these other systems’ security budgets are a function of their tokens’ worth. Sidechains, drivechains, and merged-mined chains all rely on external miners for their safety, since their safety is guaranteed in part by external miners validating their blocks. The onus on these systems is to get external miners to care enough to do so, and in the case of sidechains, drivechains, and blind merged-mined chains, there is an additional onus to encourage their nodes to mine blocks at all (since there is no on-chain reward for them to earn by doing so). By contrast, disinterested Bitcoin miners neither assist nor prevent a reorg in PoX — they only record the history of all Stacks forks. +The Stacks token (STX) is primarily meant to be used for two things (details in Stacks paper): -PoX offers two additional, unique security properties on top of PoW. First, no matter how much BTC a reorging miner can commit, the act of executing a reorg is going to be time-consuming. Unless the attacker can attack the Bitcoin chain itself by quickly producing a better Bitcoin fork, a reorging miner must sustain the attack for at least N + 1 Bitcoin blocks. This gives honest miners and users ample time to notice and react to the reorg attempt. +1. Incentives for Stacks L2 miners +2. Incentives for peg-out signers -Second, the history of block production in all Stacks forks is embedded within Bitcoin. This allows the system to leverage Bitcoin’s security budget in order to ensure that all forks are public. This is because the act of producing a hidden Stacks fork, where the fork’s block hashes are not known to the honest miners, is the act of producing a hidden canonical Bitcoin fork. Therefore, the act of producing a hidden Stacks fork is at least as hard as reorging the Bitcoin chain. A PoX chain leverages this property not to prevent reorgs, but to make reorgs unprofitable. +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. -By anchoring blocks to an existing blockchain, a PoX chain forces reorgs to happen out in the open, thereby giving advance warning to all honest network participants when they happen. Honest miners, users, and exchanges will see the PoX transactions for reorg attempts on the existing blockchain, and adapt their behaviors accordingly: honest miners will increase their commitments, and users and exchanges will require more confirmations for transactions. This makes the act of carrying out a reorg while also making a profit much more challenging, since malicious reorgs — like selfish mining and double-spending — rely on secrecy to work effectively. Specific to Stacks, miners are additionally required to mine for a “warm-up” period of two blocks, during which they must spend BTC at their target commit levels but will not win any Stacks blocks. So, a high-budget reorg attempt will not only be costly, but will also alert the rest of the network before the damage is done." +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. -- [What Kind of Blockchain is Stacks?](https://stacks.org/stacks-blockchain) +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 From f4740d0d80bb81dbbef8e240c5cbfbd1ae7c4895 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Thu, 23 Mar 2023 21:29:48 +0100 Subject: [PATCH 0996/1444] New translations btc-connection.md (Hindi) --- .../current/stacks-academy/btc-connection.md | 81 ++++++++++++++----- 1 file changed, 61 insertions(+), 20 deletions(-) diff --git a/i18n/hi/docusaurus-plugin-content-docs/current/stacks-academy/btc-connection.md b/i18n/hi/docusaurus-plugin-content-docs/current/stacks-academy/btc-connection.md index b4db915969..a3dd62f9ff 100644 --- a/i18n/hi/docusaurus-plugin-content-docs/current/stacks-academy/btc-connection.md +++ b/i18n/hi/docusaurus-plugin-content-docs/current/stacks-academy/btc-connection.md @@ -14,13 +14,37 @@ This topic is a bit of a rabbit hole, and this section of Stacks Academy is pret Let's get into it. -## Stacks Among Other Bitcoin Layers +## 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: -In the [last section](./what-is-stacks.md) we covered what Stacks actually is and what problem it is solving, but this is not a new problem. The Bitcoin write problem has been a bit of a holy grail problem in the crypto world for a while now. +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. -Bitcoin is the OG cryptocurrency and has the largest market cap, but it also some of the least functionality, which means if we want to make it a productive asset and use it to build a decentralized economy, we need to take a layered approach and let Bitcoin do what it does best, while creating additional layers on top of it to add functionality. +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. -So how does Stacks compare to some of the other approaches to layering on top of Bitcoin? +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 @@ -56,6 +80,32 @@ The Liquid consensus mechanism is managed by 15 functionaries, who handle the tr 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 follow Bitcoin finality with 100% Bitcoin hashpower. 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 designers of the Nakamoto release have decided to wait for 150 blocks before Bitcoin finality kicks in; this is mostly done to allow short-term forks to be resolved at the Stacks level. This design also means that most Maximal Extractable Value (MEV) action happens on the Stacks layer side and not on the Bitcoin side. There is always a fear of MEV incentives messing with Bitcoin mining, and the Stacks layer explicitly attracts most MEV activity to happen on the Stacks layer vs. Bitcoin L1 (the assumption here is that most MEV activity will occur within 150 blocks). Changing the variable from 150 to 6 blocks is trivial technically and can be configured as needed. Sovereign rollups effectively use a variable of 0 blocks and work similarly to the Stacks layer for reorg resistance. + +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. @@ -70,27 +120,18 @@ This is why networks like Lightning and other P2P networks don't need tokens, th 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. -But because it has its own execution environment and smart contract state to maintain, it needs a token to incentivize maintenance of the network. - -But it goes further than that. It is possible to build a system like this without a token using something like merge-mining or a sidechain, but then we lose out on the additional benefit of having the chain state's safety underpinned by its entire token economy's value. - -In the case of Stacks, the safety and liveness of the chain are underpinned by this value, and the stacking mechanism incentivizes network members to increase this value. - -From Jude Nelson, Stacks core developer: - -"How hard is it to cause a safety failure (i.e. a double-spend via a reorg) on just the canonical Stacks chain fork? Anyone can become a miner by spending BTC, so without loss of generality, reverting the last block on the canonical chain is at least as hard in expectation as spending more BTC than the rest of the miners combined for that block. Because each Bitcoin block selects at most one Stacks block, the act of reorging the canonical Stacks chain back N blocks is the act of winning at least N + 1 blocks built off of a common ancestor that is N blocks deep. This is a lower bound on the number of Bitcoin blocks mined during which a reorg needs to take place — in practice, honest miners will keep working on the canonical chain, and will win some Stacks blocks of their own, which in turn increases the number of Stacks blocks the reorging miners must win. - -How costly is it to carry out a reorg of N blocks? It’s a function of how valuable STX is relative to BTC — the more valuable STX are, the more BTC honest miners are committing to mining (this has borne out in practice), and thus the more BTC a reorging miner must commit. Therefore, the cost of a reorg is a function of the value of STX. +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. -This is similar to the economic security of a PoW blockchain. Like in PoW, each fork of the Stacks chain has its own independent “security budget” — an attacker must out-spend the security budget to carry out a reorg, and the security budget is a function of the block rewards. In PoX, the only difference is that the miners spend another blockchain’s tokens (BTC in Stacks’ case) instead of energy. Therefore, Stacks can’t be a sidechain, a drivechain, or a merge-mined chain, because none of these other systems’ security budgets are a function of their tokens’ worth. Sidechains, drivechains, and merged-mined chains all rely on external miners for their safety, since their safety is guaranteed in part by external miners validating their blocks. The onus on these systems is to get external miners to care enough to do so, and in the case of sidechains, drivechains, and blind merged-mined chains, there is an additional onus to encourage their nodes to mine blocks at all (since there is no on-chain reward for them to earn by doing so). By contrast, disinterested Bitcoin miners neither assist nor prevent a reorg in PoX — they only record the history of all Stacks forks. +The Stacks token (STX) is primarily meant to be used for two things (details in Stacks paper): -PoX offers two additional, unique security properties on top of PoW. First, no matter how much BTC a reorging miner can commit, the act of executing a reorg is going to be time-consuming. Unless the attacker can attack the Bitcoin chain itself by quickly producing a better Bitcoin fork, a reorging miner must sustain the attack for at least N + 1 Bitcoin blocks. This gives honest miners and users ample time to notice and react to the reorg attempt. +1. Incentives for Stacks L2 miners +2. Incentives for peg-out signers -Second, the history of block production in all Stacks forks is embedded within Bitcoin. This allows the system to leverage Bitcoin’s security budget in order to ensure that all forks are public. This is because the act of producing a hidden Stacks fork, where the fork’s block hashes are not known to the honest miners, is the act of producing a hidden canonical Bitcoin fork. Therefore, the act of producing a hidden Stacks fork is at least as hard as reorging the Bitcoin chain. A PoX chain leverages this property not to prevent reorgs, but to make reorgs unprofitable. +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. -By anchoring blocks to an existing blockchain, a PoX chain forces reorgs to happen out in the open, thereby giving advance warning to all honest network participants when they happen. Honest miners, users, and exchanges will see the PoX transactions for reorg attempts on the existing blockchain, and adapt their behaviors accordingly: honest miners will increase their commitments, and users and exchanges will require more confirmations for transactions. This makes the act of carrying out a reorg while also making a profit much more challenging, since malicious reorgs — like selfish mining and double-spending — rely on secrecy to work effectively. Specific to Stacks, miners are additionally required to mine for a “warm-up” period of two blocks, during which they must spend BTC at their target commit levels but will not win any Stacks blocks. So, a high-budget reorg attempt will not only be costly, but will also alert the rest of the network before the damage is done." +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. -- [What Kind of Blockchain is Stacks?](https://stacks.org/stacks-blockchain) +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 From dbd5f686b1d2374f9e46ef68466be7280b0a9e25 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Thu, 23 Mar 2023 22:41:57 +0100 Subject: [PATCH 0997/1444] Update source file btc-connection.md --- docs/stacks-academy/btc-connection.md | 81 ++++++++++++++++++++------- 1 file changed, 61 insertions(+), 20 deletions(-) diff --git a/docs/stacks-academy/btc-connection.md b/docs/stacks-academy/btc-connection.md index 5f7e7f32bb..105c15d83d 100644 --- a/docs/stacks-academy/btc-connection.md +++ b/docs/stacks-academy/btc-connection.md @@ -14,13 +14,37 @@ This topic is a bit of a rabbit hole, and this section of Stacks Academy is pret Let's get into it. -## Stacks Among Other Bitcoin Layers +## 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: -In the [last section](./what-is-stacks.md) we covered what Stacks actually is and what problem it is solving, but this is not a new problem. The Bitcoin write problem has been a bit of a holy grail problem in the crypto world for a while now. +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. -Bitcoin is the OG cryptocurrency and has the largest market cap, but it also some of the least functionality, which means if we want to make it a productive asset and use it to build a decentralized economy, we need to take a layered approach and let Bitcoin do what it does best, while creating additional layers on top of it to add functionality. +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. -So how does Stacks compare to some of the other approaches to layering on top of Bitcoin? +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 @@ -56,6 +80,32 @@ The Liquid consensus mechanism is managed by 15 functionaries, who handle the tr 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 follow Bitcoin finality with 100% Bitcoin hashpower. 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 designers of the Nakamoto release have decided to wait for 150 blocks before Bitcoin finality kicks in; this is mostly done to allow short-term forks to be resolved at the Stacks level. This design also means that most Maximal Extractable Value (MEV) action happens on the Stacks layer side and not on the Bitcoin side. There is always a fear of MEV incentives messing with Bitcoin mining, and the Stacks layer explicitly attracts most MEV activity to happen on the Stacks layer vs. Bitcoin L1 (the assumption here is that most MEV activity will occur within 150 blocks). Changing the variable from 150 to 6 blocks is trivial technically and can be configured as needed. Sovereign rollups effectively use a variable of 0 blocks and work similarly to the Stacks layer for reorg resistance. + +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. @@ -70,27 +120,18 @@ This is why networks like Lightning and other P2P networks don't need tokens, th 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. -But because it has its own execution environment and smart contract state to maintain, it needs a token to incentivize maintenance of the network. - -But it goes further than that. It is possible to build a system like this without a token using something like merge-mining or a sidechain, but then we lose out on the additional benefit of having the chain state's safety underpinned by its entire token economy's value. - -In the case of Stacks, the safety and liveness of the chain are underpinned by this value, and the stacking mechanism incentivizes network members to increase this value. - -From Jude Nelson, Stacks core developer: - -"How hard is it to cause a safety failure (i.e. a double-spend via a reorg) on just the canonical Stacks chain fork? Anyone can become a miner by spending BTC, so without loss of generality, reverting the last block on the canonical chain is at least as hard in expectation as spending more BTC than the rest of the miners combined for that block. Because each Bitcoin block selects at most one Stacks block, the act of reorging the canonical Stacks chain back N blocks is the act of winning at least N + 1 blocks built off of a common ancestor that is N blocks deep. This is a lower bound on the number of Bitcoin blocks mined during which a reorg needs to take place — in practice, honest miners will keep working on the canonical chain, and will win some Stacks blocks of their own, which in turn increases the number of Stacks blocks the reorging miners must win. - -How costly is it to carry out a reorg of N blocks? It’s a function of how valuable STX is relative to BTC — the more valuable STX are, the more BTC honest miners are committing to mining (this has borne out in practice), and thus the more BTC a reorging miner must commit. Therefore, the cost of a reorg is a function of the value of STX. +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. -This is similar to the economic security of a PoW blockchain. Like in PoW, each fork of the Stacks chain has its own independent “security budget” — an attacker must out-spend the security budget to carry out a reorg, and the security budget is a function of the block rewards. In PoX, the only difference is that the miners spend another blockchain’s tokens (BTC in Stacks’ case) instead of energy. Therefore, Stacks can’t be a sidechain, a drivechain, or a merge-mined chain, because none of these other systems’ security budgets are a function of their tokens’ worth. Sidechains, drivechains, and merged-mined chains all rely on external miners for their safety, since their safety is guaranteed in part by external miners validating their blocks. The onus on these systems is to get external miners to care enough to do so, and in the case of sidechains, drivechains, and blind merged-mined chains, there is an additional onus to encourage their nodes to mine blocks at all (since there is no on-chain reward for them to earn by doing so). By contrast, disinterested Bitcoin miners neither assist nor prevent a reorg in PoX — they only record the history of all Stacks forks. +The Stacks token (STX) is primarily meant to be used for two things (details in Stacks paper): -PoX offers two additional, unique security properties on top of PoW. First, no matter how much BTC a reorging miner can commit, the act of executing a reorg is going to be time-consuming. Unless the attacker can attack the Bitcoin chain itself by quickly producing a better Bitcoin fork, a reorging miner must sustain the attack for at least N + 1 Bitcoin blocks. This gives honest miners and users ample time to notice and react to the reorg attempt. +1. Incentives for Stacks L2 miners +2. Incentives for peg-out signers -Second, the history of block production in all Stacks forks is embedded within Bitcoin. This allows the system to leverage Bitcoin’s security budget in order to ensure that all forks are public. This is because the act of producing a hidden Stacks fork, where the fork’s block hashes are not known to the honest miners, is the act of producing a hidden canonical Bitcoin fork. Therefore, the act of producing a hidden Stacks fork is at least as hard as reorging the Bitcoin chain. A PoX chain leverages this property not to prevent reorgs, but to make reorgs unprofitable. +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. -By anchoring blocks to an existing blockchain, a PoX chain forces reorgs to happen out in the open, thereby giving advance warning to all honest network participants when they happen. Honest miners, users, and exchanges will see the PoX transactions for reorg attempts on the existing blockchain, and adapt their behaviors accordingly: honest miners will increase their commitments, and users and exchanges will require more confirmations for transactions. This makes the act of carrying out a reorg while also making a profit much more challenging, since malicious reorgs — like selfish mining and double-spending — rely on secrecy to work effectively. Specific to Stacks, miners are additionally required to mine for a “warm-up” period of two blocks, during which they must spend BTC at their target commit levels but will not win any Stacks blocks. So, a high-budget reorg attempt will not only be costly, but will also alert the rest of the network before the damage is done." +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. -- [What Kind of Blockchain is Stacks?](https://stacks.org/stacks-blockchain) +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 From 291172bb6ef9fff7200771a5b9f4a02452709bda Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 9 Apr 2023 23:44:06 +0200 Subject: [PATCH 0998/1444] New translations _category_.json (Spanish) --- .../current/clarity/noteworthy-contracts/_category_.json | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/i18n/es/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/_category_.json b/i18n/es/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/_category_.json index 14b9388b4d..ff3b96c544 100644 --- a/i18n/es/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/_category_.json +++ b/i18n/es/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/_category_.json @@ -1,8 +1,8 @@ { - "label": "Noteworthy Contracts", + "label": "Contratos importantes", "position": 4, "link": { "type": "generated-index", - "description": "Specific deployed Clarity Contracts worth mentioning." + "description": "Contratos de Clarity desplegados específicos que valen la pena mencionar." } } From 2226190be7e8743c6152a3a3840ee00dd919e484 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 9 Apr 2023 23:44:07 +0200 Subject: [PATCH 0999/1444] New translations bns-contract.md (Spanish) --- .../noteworthy-contracts/bns-contract.md | 60 +++++++++---------- 1 file changed, 30 insertions(+), 30 deletions(-) diff --git a/i18n/es/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/bns-contract.md b/i18n/es/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/bns-contract.md index 8f0849b1dd..8599bb7ff2 100644 --- a/i18n/es/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/bns-contract.md +++ b/i18n/es/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/bns-contract.md @@ -1,21 +1,21 @@ --- -title: BNS Contract -description: The Bitcoin Name System. +title: Contrato BNS +description: El Sistema de Nombres de Bitcoin. --- ![](/img/satoshi-btc.png) ## Introducción -The Bitcoin Name System (BNS) is implemented as a smart contract using Clarity. +El Sistema de Nombres Bitcoin (Bitcoin Name System, en inglés abreviado como BNS) se implementa como un contrato inteligente usando Clarity. -Below is a list of public and read-only functions as well as error codes that can be returned by those methods: +A continuación se muestra una lista de funciones públicas y de solo lectura, así como los códigos de error que pueden devolver esos métodos: -- [Public functions](#public-functions) -- [Read-only functions](#read-only-functions) -- [Error codes](#error-codes) +- [Funciones públicas](#public-functions) +- [Funciones de solo lectura](#read-only-functions) +- [Códigos de error](#error-codes) -## Public functions +## Funciones públicas ### name-import @@ -25,9 +25,9 @@ Below is a list of public and read-only functions as well as error codes that ca #### Signature: `(name-import namespace name beneficiary zonefile-hash)` -#### Description: +#### Descripción: -Imports name to a revealed namespace. Each imported name is given both an owner and some off-chain state. +Importa un nombre a un espacio de nombres revelado. Each imported name is given both an owner and some off-chain state. ### name-preorder @@ -37,7 +37,7 @@ Imports name to a revealed namespace. Each imported name is given both an owner #### Signature: `(name-preorder hashed-salted-fqn stx-to-burn)` -#### Description: +#### Descripción: 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. @@ -49,7 +49,7 @@ Preorders a name by telling all BNS nodes the salted hash of the BNS name. It pa #### Signature: `(name-register namespace name salt zonefile-hash)` -#### Description: +#### Descripción: Reveals the salt and the name to all BNS nodes, and assigns the name an initial public key hash and zone file hash. @@ -61,7 +61,7 @@ Reveals the salt and the name to all BNS nodes, and assigns the name an initial #### Signature: `(name-renewal namespace name stx-to-burn new-owner zonefile-hash)` -#### Description: +#### 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. @@ -77,7 +77,7 @@ It will stop resolving in the grace period, and all of the above operations will #### Signature: `(name-revoke namespace name)` -#### Description: +#### 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. @@ -89,7 +89,7 @@ Makes a name unresolvable. The BNS consensus rules stipulate that once a name is #### Signature: `(name-transfer namespace name new-owner zonefile-hash)` -#### Description: +#### Descripción: Changes the name's public key hash. You would send a name transfer transaction if you wanted to: @@ -107,7 +107,7 @@ When transferring a name, you have the option to also clear the name's zone file #### Signature: `(name-update namespace name zonefile-hash)` -#### Description: +#### 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. @@ -119,7 +119,7 @@ Changes the name's zone file hash. You would send a name update transaction if y #### Signature: `(namespace-preorder hashed-salted-namespace stx-to-burn)` -#### Description: +#### 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). @@ -131,7 +131,7 @@ Registers the salted hash of the namespace with BNS nodes, and burns the requisi #### Signature: `(namespace-ready namespace)` -#### Description: +#### 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. @@ -143,7 +143,7 @@ Launches the namespace and makes it available to the public. Once a namespace is #### 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: +#### 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. @@ -166,7 +166,7 @@ Example: - buckets 7, 8, 9, 10, 11, 12, 13, 14: 7 - buckets 15, 16+: -## Read-only functions +## Funciones de solo lectura ### can-name-be-registered @@ -176,7 +176,7 @@ Example: #### Signature: `(can-name-be-registered namespace name)` -#### Description: +#### Descripción: Returns true if the provided name can be registered. @@ -188,7 +188,7 @@ Returns true if the provided name can be registered. #### Signature: `(can-namespace-be-registered namespace)` -#### Description: +#### Descripción: Returns true if the provided namespace is available. @@ -200,7 +200,7 @@ Returns true if the provided namespace is available. #### Signature: `(can-receive-name owner)` -#### Description: +#### Descripción: 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. @@ -212,7 +212,7 @@ Returns true if the provided name can be received. That is, if it is not current #### Signature: `(get-name-price namespace name)` -#### Description: +#### Descripción: Gets the price for a name. @@ -224,7 +224,7 @@ Gets the price for a name. #### Signature: `(get-namespace-price namespace)` -#### Description: +#### Descripción: Gets the price for a namespace. @@ -236,7 +236,7 @@ Gets the price for a namespace. #### Signature: `(get-namespace-properties namespace)` -#### Description: +#### Descripción: Get namespace properties. @@ -248,7 +248,7 @@ Get namespace properties. #### Signature: `(is-name-lease-expired namespace name)` -#### Description: +#### Descripción: Return true if the provided name lease is expired. @@ -260,7 +260,7 @@ Return true if the provided name lease is expired. #### Signature: `(name-resolve namespace name)` -#### Description: +#### Descripción: Get name registration details. @@ -272,11 +272,11 @@ Get name registration details. #### Signature: `(resolve-principal owner)` -#### Description: +#### Descripción: Returns the registered name that a principal owns if there is one. A principal can only own one name at a time. -## Error codes +## Códigos de error ### ERR_INSUFFICIENT_FUNDS From f9664780014d5989ffdec17ea31a64a85cb5b957 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sun, 9 Apr 2023 23:44:08 +0200 Subject: [PATCH 1000/1444] New translations stacking-contract.md (Spanish) --- .../noteworthy-contracts/stacking-contract.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/i18n/es/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/stacking-contract.md b/i18n/es/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/stacking-contract.md index 0ee88e2224..13443bf2b2 100644 --- a/i18n/es/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/stacking-contract.md +++ b/i18n/es/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/stacking-contract.md @@ -8,13 +8,13 @@ sidebar_position: 6 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: +A continuación se muestra una lista de funciones públicas y de solo lectura, así como los códigos de error que pueden devolver esos métodos: -- [Public functions](#public-functions) -- [Read-only functions](#read-only-functions) -- [Error codes](#error-codes) +- [Funciones públicas](#public-functions) +- [Funciones de solo lectura](#read-only-functions) +- [Códigos de error](#error-codes) -## Public functions +## Funciones públicas ### allow-contract-caller @@ -149,7 +149,7 @@ This is the self-service interface. tx-sender will be the Stacker. The tokens will unlock and be returned to the Stacker (tx-sender) automatically. -## Read-only functions +## Funciones de solo lectura ### can-stack-stx @@ -235,7 +235,7 @@ Returns the amount of currently participating uSTX in the given cycle. Returns whether or not PoX has been rejected at a given PoX cycle. -## Error codes +## Códigos de error ### ERR_DELEGATION_EXPIRES_DURING_LOCK From d0df4413c07daf7a2b1ad36d27f8170de3261223 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Mon, 10 Apr 2023 00:52:31 +0200 Subject: [PATCH 1001/1444] New translations bns-contract.md (Spanish) --- .../clarity/noteworthy-contracts/bns-contract.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/i18n/es/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/bns-contract.md b/i18n/es/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/bns-contract.md index 8599bb7ff2..a8b81c7655 100644 --- a/i18n/es/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/bns-contract.md +++ b/i18n/es/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/bns-contract.md @@ -27,7 +27,7 @@ A continuación se muestra una lista de funciones públicas y de solo lectura, a #### Descripción: -Importa un nombre a un espacio de nombres revelado. Each imported name is given both an owner and some off-chain state. +Importa un nombre a un namespace revelado. A cada nombre importado se le asigna tanto un propietario como un estado off-chain. ### name-preorder @@ -39,7 +39,7 @@ Importa un nombre a un espacio de nombres revelado. Each imported name is given #### Descripción: -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. +Reserva un nombre informando a todos los nodos de BNS el hash salt del nombre de BNS. Se paga la tarifa de registro a la dirección designada por el propietario del namespace. ### name-register @@ -51,7 +51,7 @@ Preorders a name by telling all BNS nodes the salted hash of the BNS name. It pa #### Descripción: -Reveals the salt and the name to all BNS nodes, and assigns the name an initial public key hash and zone file hash. +Revela el 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 @@ -63,11 +63,11 @@ Reveals the salt and the name to all BNS nodes, and assigns the name an initial #### 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. +Dependiendo de las reglas del namespace, un nombre puede expirar. Por ejemplo, los nombres en el namespace .id expiran después de 2 años. Necesitas enviar una renovación de nombre de vez en cuando para mantener tu nombre. -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. +Pagará el coste de registro de su nombre a la dirección de grabación designada por el namespace cuando lo renueve. Cuando un nombre caduca, ingresa a un \"período de gracia\". El período está fijado en 5000 bloques (un mes) pero puede configurarse para cada 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. +Dejará de resolverse en el período de gracia, y todas las operaciones anteriores dejarán de ser reconocidas por las reglas de consenso de BNS. Sin embargo, puede enviar un NAME_RENEWAL durante este período de gracia para preservar su nombre. Después del período de gracia, cualquier persona puede registrar ese nombre nuevamente. Si su nombre está en un namespace donde los nombres no caducan, entonces nunca necesitará usar esta transacción. ### name-revoke From 46d72731ee2de32f266952fe0ba937340bea6c4e Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Mon, 10 Apr 2023 02:18:00 +0200 Subject: [PATCH 1002/1444] New translations bns-contract.md (Spanish) --- .../clarity/noteworthy-contracts/bns-contract.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/i18n/es/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/bns-contract.md b/i18n/es/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/bns-contract.md index a8b81c7655..7f5d1bfcc8 100644 --- a/i18n/es/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/bns-contract.md +++ b/i18n/es/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/bns-contract.md @@ -79,7 +79,7 @@ Dejará de resolverse en el período de gracia, y todas las operaciones anterior #### 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. +Hace que un nombre no se pueda resolver. Las reglas de consenso de BNS estipulan que una vez que se revoca un nombre, nadie puede cambiar su hash de clave pública ni su hash de archivo de zona. El hash del archivo de zona del nombre se establece en nulo para evitar que se resuelva. Deberías hacer esto solo si tu clave privada ha sido comprometida, o si deseas que tu nombre no se pueda usar por alguna razón. ### name-transfer @@ -91,13 +91,13 @@ Makes a name unresolvable. The BNS consensus rules stipulate that once a name is #### Descripción: -Changes the name's public key hash. You would send a name transfer transaction if you wanted to: +Cambia el hash de clave pública del nombre. Enviarías una transacción de transferencia de nombre si quisieras: -- Change your private key -- Send the name to someone else or -- Update your zone file +- Cambiar tu llave privada +- Enviar el nombre a otra persona o +- Actualizar tu archivo de zona -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. +Al transferir un nombre, tienes la opción de también borrar el hash del archivo de zona del nombre (es decir, establecerlo en nulo). Esto es útil cuando envías el nombre a otra persona, para que el nombre del destinatario no resuelva a tu archivo de zona. ### name-update @@ -109,7 +109,7 @@ When transferring a name, you have the option to also clear the name's zone file #### 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. +Cambia el hash del archivo de zona del nombre. Enviarías una transacción de actualización de nombre si quisieras cambiar el contenido del archivo de la zona del nombre. Por ejemplo, harías esto si quieres desplegar tu propio hub de Gaia y deseas que otras personas lean desde él. ### namespace-preorder From 45088a02135c05c0f2b3c85f82a3093904fd743b Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Mon, 10 Apr 2023 03:27:47 +0200 Subject: [PATCH 1003/1444] New translations bns-contract.md (Spanish) --- .../noteworthy-contracts/bns-contract.md | 36 +++++++++---------- 1 file changed, 18 insertions(+), 18 deletions(-) diff --git a/i18n/es/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/bns-contract.md b/i18n/es/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/bns-contract.md index 7f5d1bfcc8..62c7c60462 100644 --- a/i18n/es/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/bns-contract.md +++ b/i18n/es/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/bns-contract.md @@ -121,7 +121,7 @@ Cambia el hash del archivo de zona del nombre. Enviarías una transacción de ac #### 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). +Registra el hash salted del namespace con los nodos de BNS y quema la cantidad requerida de criptomoneda. Además, este paso demuestra a los nodos de BNS que el usuario ha respetado las reglas de consenso de BNS al incluir un hash de consenso reciente en la transacción. Devuelve la fecha de vencimiento del pre-pedido (en bloques). ### namespace-ready @@ -133,7 +133,7 @@ Registers the salted hash of the namespace with BNS nodes, and burns the requisi #### 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. +Lanza el namespace y lo hace disponible al público. Una vez que se lanza un namespace, cualquiera puede registrar un nombre en él si paga la cantidad apropiada de criptomonedas. ### namespace-reveal @@ -145,22 +145,22 @@ Launches the namespace and makes it available to the public. Once a namespace is #### 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. +Revela el salt y el ID del namespace (después de una preo orden del namespace). Muestra cuánto tiempo duran los nombres en este namespace antes de que caduquen o deban ser renovados, y establece una función de precio para el namespace que determina cuán barato o caro serán sus nombres. Todos los parámetros prefijados por `p` componen la `price function`. Estos parámetros rigen el precio y el tiempo de vida de los nombres en el namespace. -The rules for a namespace are as follows: +Las reglas para un namespace son las siguientes: -- a name can fall into one of 16 buckets, measured by length. Bucket 16 incorporates all names at least 16 characters long. +- un nombre puede caer en uno de los 16 buckets, medidos por longitud. El bucket 16 incorpora todos los nombres al menos de 16 caracteres de longitud. -- the pricing structure applies a multiplicative penalty for having numeric characters, or punctuation characters. +- la estructura de precios aplica una penalización multiplicativa por tener caracteres numéricos, o caracteres de puntuación. -- the price of a name in a bucket is `((coeff) * (base) ^ (bucket exponent)) / ((numeric discount multiplier) * (punctuation discount multiplier))` +- el precio de un nombre en un bucket es `((coeff) * (base) ^ (exponente del bucket)) / ((multiplicador de descuento numérico) * (multiplicador de descuento de puntuación))` -Example: +Ejemplo: - base = 10 - coeff = 2 -- nonalpha discount: 10 -- no-vowel discount: 10 +- descuento nonalpha: 10 +- descuento no-vocal: 10 - buckets 1, 2: 9 - buckets 3, 4, 5, 6: 8 - buckets 7, 8, 9, 10, 11, 12, 13, 14: 7 @@ -178,7 +178,7 @@ Example: #### Descripción: -Returns true if the provided name can be registered. +Devuelve verdadero si el nombre proporcionado puede ser registrado. ### can-namespace-be-registered @@ -190,7 +190,7 @@ Returns true if the provided name can be registered. #### Descripción: -Returns true if the provided namespace is available. +Devuelve verdadero si el namespace proporcionado está disponible. ### can-receive-name @@ -202,7 +202,7 @@ Returns true if the provided namespace is available. #### Descripción: -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. +Devuelve verdadero si el nombre proporcionado puede ser recibido. Es decir, si actualmente no está en propiedad de alguien, un arrendamiento anterior ha caducado y el nombre no ha sido revocado. ### get-name-price @@ -226,7 +226,7 @@ Gets the price for a name. #### Descripción: -Gets the price for a namespace. +Obtiene el precio de un namespace. ### get-namespace-properties @@ -238,7 +238,7 @@ Gets the price for a namespace. #### Descripción: -Get namespace properties. +Obtener propiedades del namespace. ### is-name-lease-expired @@ -250,7 +250,7 @@ Get namespace properties. #### Descripción: -Return true if the provided name lease is expired. +Devuelve verdadero si el contrato de arrendamiento del nombre proporcionado ha caducado. ### name-resolve @@ -262,7 +262,7 @@ Return true if the provided name lease is expired. #### Descripción: -Get name registration details. +Obtener detalles de registro de nombres. ### resolve-principal @@ -274,7 +274,7 @@ Get name registration details. #### Descripción: -Returns the registered name that a principal owns if there is one. A principal can only own one name at a time. +Devuelve el nombre registrado que posee un principal si existe alguno. Un principal solo puede poseer un nombre a la vez. ## Códigos de error From 839dd2414ea28c0479f1608de42cc502a6e8ebd8 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Fri, 28 Apr 2023 01:42:17 +0200 Subject: [PATCH 1004/1444] New translations index.md (French) --- i18n/fr/docusaurus-plugin-content-docs/current/clarity/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/clarity/index.md b/i18n/fr/docusaurus-plugin-content-docs/current/clarity/index.md index 903de93a45..fd941bc266 100644 --- a/i18n/fr/docusaurus-plugin-content-docs/current/clarity/index.md +++ b/i18n/fr/docusaurus-plugin-content-docs/current/clarity/index.md @@ -27,7 +27,7 @@ Clarity code is interpreted and committed to the chain exactly as written. Solid ### 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. If you are unsure what this means, let it not worry you for now. The serious advantage of decidability will become more apparent over time. +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 From 96b349be453c4e0978e4cf8df287e238d6e40daa Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Fri, 28 Apr 2023 01:42:18 +0200 Subject: [PATCH 1005/1444] New translations _category_.json (French) --- .../current/clarity/noteworthy-contracts/_category_.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/_category_.json b/i18n/fr/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/_category_.json index 14b9388b4d..eb32d48e32 100644 --- a/i18n/fr/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/_category_.json +++ b/i18n/fr/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/_category_.json @@ -1,6 +1,6 @@ { "label": "Noteworthy Contracts", - "position": 4, + "position": 5, "link": { "type": "generated-index", "description": "Specific deployed Clarity Contracts worth mentioning." From 1435a16b9a9eee30f5642b1bc2a25c3e32373d25 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Fri, 28 Apr 2023 01:42:19 +0200 Subject: [PATCH 1006/1444] New translations decidable.md (French) --- .../current/clarity/security/decidable.md | 174 ++++++++++++++++++ 1 file changed, 174 insertions(+) create mode 100644 i18n/fr/docusaurus-plugin-content-docs/current/clarity/security/decidable.md diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/clarity/security/decidable.md b/i18n/fr/docusaurus-plugin-content-docs/current/clarity/security/decidable.md new file mode 100644 index 0000000000..787e017fee --- /dev/null +++ b/i18n/fr/docusaurus-plugin-content-docs/current/clarity/security/decidable.md @@ -0,0 +1,174 @@ +--- +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 in regards to the security advantages of Clarity, but what do they mean? + +While related, they are not quite interchangeable, and there are a few differences. + +### Non-Turing Complete + +A system or language is considered 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, which 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, especially those involving unbounded loops or recursion. 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 that thinking is that it opens up smart contract security to greater human error. 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 will prevent a problem like this. + +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 would force us as developers to think of a better solution to our problem, like 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 greatly 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, and 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. From 9b673f8f6dac764d01f86169b570b0a9b00b3855 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Fri, 28 Apr 2023 01:42:19 +0200 Subject: [PATCH 1007/1444] New translations index.md (French) --- .../current/clarity/security/index.md | 22 +++++++++++++++++++ 1 file changed, 22 insertions(+) create mode 100644 i18n/fr/docusaurus-plugin-content-docs/current/clarity/security/index.md diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/clarity/security/index.md b/i18n/fr/docusaurus-plugin-content-docs/current/clarity/security/index.md new file mode 100644 index 0000000000..90aa31abb4 --- /dev/null +++ b/i18n/fr/docusaurus-plugin-content-docs/current/clarity/security/index.md @@ -0,0 +1,22 @@ +--- +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) From d5b2b862a932c7b2609220f97bf28217713fe707 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Fri, 28 Apr 2023 01:42:22 +0200 Subject: [PATCH 1008/1444] New translations index.md (Spanish) --- i18n/es/docusaurus-plugin-content-docs/current/clarity/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/i18n/es/docusaurus-plugin-content-docs/current/clarity/index.md b/i18n/es/docusaurus-plugin-content-docs/current/clarity/index.md index 908a4bea3a..34bcc6aa3d 100644 --- a/i18n/es/docusaurus-plugin-content-docs/current/clarity/index.md +++ b/i18n/es/docusaurus-plugin-content-docs/current/clarity/index.md @@ -27,7 +27,7 @@ Clarity code is interpreted and committed to the chain exactly as written. Solid ### 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. If you are unsure what this means, let it not worry you for now. The serious advantage of decidability will become more apparent over time. +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 From e2fd4e212d58104bd14b3b887201a038ec7c636c Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Fri, 28 Apr 2023 01:42:23 +0200 Subject: [PATCH 1009/1444] New translations _category_.json (Spanish) --- .../current/clarity/noteworthy-contracts/_category_.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/i18n/es/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/_category_.json b/i18n/es/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/_category_.json index ff3b96c544..ad9f9d75a7 100644 --- a/i18n/es/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/_category_.json +++ b/i18n/es/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/_category_.json @@ -1,6 +1,6 @@ { "label": "Contratos importantes", - "position": 4, + "position": 5, "link": { "type": "generated-index", "description": "Contratos de Clarity desplegados específicos que valen la pena mencionar." From b430be591ea70b5ac0853e3fab62f998b21eac14 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Fri, 28 Apr 2023 01:42:24 +0200 Subject: [PATCH 1010/1444] New translations decidable.md (Spanish) --- .../current/clarity/security/decidable.md | 174 ++++++++++++++++++ 1 file changed, 174 insertions(+) create mode 100644 i18n/es/docusaurus-plugin-content-docs/current/clarity/security/decidable.md diff --git a/i18n/es/docusaurus-plugin-content-docs/current/clarity/security/decidable.md b/i18n/es/docusaurus-plugin-content-docs/current/clarity/security/decidable.md new file mode 100644 index 0000000000..787e017fee --- /dev/null +++ b/i18n/es/docusaurus-plugin-content-docs/current/clarity/security/decidable.md @@ -0,0 +1,174 @@ +--- +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 in regards to the security advantages of Clarity, but what do they mean? + +While related, they are not quite interchangeable, and there are a few differences. + +### Non-Turing Complete + +A system or language is considered 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, which 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, especially those involving unbounded loops or recursion. 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 that thinking is that it opens up smart contract security to greater human error. 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 will prevent a problem like this. + +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 would force us as developers to think of a better solution to our problem, like 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 greatly 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, and 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. From 4df1d4133cdd40cca1404a58390037b4b5e4bb64 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Fri, 28 Apr 2023 01:42:25 +0200 Subject: [PATCH 1011/1444] New translations index.md (Spanish) --- .../current/clarity/security/index.md | 22 +++++++++++++++++++ 1 file changed, 22 insertions(+) create mode 100644 i18n/es/docusaurus-plugin-content-docs/current/clarity/security/index.md diff --git a/i18n/es/docusaurus-plugin-content-docs/current/clarity/security/index.md b/i18n/es/docusaurus-plugin-content-docs/current/clarity/security/index.md new file mode 100644 index 0000000000..90aa31abb4 --- /dev/null +++ b/i18n/es/docusaurus-plugin-content-docs/current/clarity/security/index.md @@ -0,0 +1,22 @@ +--- +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) From dc10910dffe43cfbe438ba8a99d9e7973a76f41f Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Fri, 28 Apr 2023 01:42:27 +0200 Subject: [PATCH 1012/1444] New translations index.md (German) --- i18n/de/docusaurus-plugin-content-docs/current/clarity/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/i18n/de/docusaurus-plugin-content-docs/current/clarity/index.md b/i18n/de/docusaurus-plugin-content-docs/current/clarity/index.md index 903de93a45..fd941bc266 100644 --- a/i18n/de/docusaurus-plugin-content-docs/current/clarity/index.md +++ b/i18n/de/docusaurus-plugin-content-docs/current/clarity/index.md @@ -27,7 +27,7 @@ Clarity code is interpreted and committed to the chain exactly as written. Solid ### 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. If you are unsure what this means, let it not worry you for now. The serious advantage of decidability will become more apparent over time. +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 From 4dc534fd5c2917ffc545f086f333ba10a889ea41 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Fri, 28 Apr 2023 01:42:28 +0200 Subject: [PATCH 1013/1444] New translations _category_.json (German) --- .../current/clarity/noteworthy-contracts/_category_.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/i18n/de/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/_category_.json b/i18n/de/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/_category_.json index 14b9388b4d..eb32d48e32 100644 --- a/i18n/de/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/_category_.json +++ b/i18n/de/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/_category_.json @@ -1,6 +1,6 @@ { "label": "Noteworthy Contracts", - "position": 4, + "position": 5, "link": { "type": "generated-index", "description": "Specific deployed Clarity Contracts worth mentioning." From b332fcec4371009c4de84e2f9dfd070cd8be1733 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Fri, 28 Apr 2023 01:42:29 +0200 Subject: [PATCH 1014/1444] New translations decidable.md (German) --- .../current/clarity/security/decidable.md | 174 ++++++++++++++++++ 1 file changed, 174 insertions(+) create mode 100644 i18n/de/docusaurus-plugin-content-docs/current/clarity/security/decidable.md diff --git a/i18n/de/docusaurus-plugin-content-docs/current/clarity/security/decidable.md b/i18n/de/docusaurus-plugin-content-docs/current/clarity/security/decidable.md new file mode 100644 index 0000000000..787e017fee --- /dev/null +++ b/i18n/de/docusaurus-plugin-content-docs/current/clarity/security/decidable.md @@ -0,0 +1,174 @@ +--- +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 in regards to the security advantages of Clarity, but what do they mean? + +While related, they are not quite interchangeable, and there are a few differences. + +### Non-Turing Complete + +A system or language is considered 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, which 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, especially those involving unbounded loops or recursion. 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 that thinking is that it opens up smart contract security to greater human error. 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 will prevent a problem like this. + +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 would force us as developers to think of a better solution to our problem, like 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 greatly 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, and 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. From 6733f92ba283e0094aa3845faf2185d3be8f56f0 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Fri, 28 Apr 2023 01:42:30 +0200 Subject: [PATCH 1015/1444] New translations index.md (German) --- .../current/clarity/security/index.md | 22 +++++++++++++++++++ 1 file changed, 22 insertions(+) create mode 100644 i18n/de/docusaurus-plugin-content-docs/current/clarity/security/index.md diff --git a/i18n/de/docusaurus-plugin-content-docs/current/clarity/security/index.md b/i18n/de/docusaurus-plugin-content-docs/current/clarity/security/index.md new file mode 100644 index 0000000000..90aa31abb4 --- /dev/null +++ b/i18n/de/docusaurus-plugin-content-docs/current/clarity/security/index.md @@ -0,0 +1,22 @@ +--- +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) From 828d88d351368a888a226512dfbdbebfefe59f95 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Fri, 28 Apr 2023 01:42:32 +0200 Subject: [PATCH 1016/1444] New translations index.md (Japanese) --- i18n/ja/docusaurus-plugin-content-docs/current/clarity/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/clarity/index.md b/i18n/ja/docusaurus-plugin-content-docs/current/clarity/index.md index 903de93a45..fd941bc266 100644 --- a/i18n/ja/docusaurus-plugin-content-docs/current/clarity/index.md +++ b/i18n/ja/docusaurus-plugin-content-docs/current/clarity/index.md @@ -27,7 +27,7 @@ Clarity code is interpreted and committed to the chain exactly as written. Solid ### 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. If you are unsure what this means, let it not worry you for now. The serious advantage of decidability will become more apparent over time. +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 From 35d56ed7160328a26afdaca3d04e5be6cf404f3f Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Fri, 28 Apr 2023 01:42:33 +0200 Subject: [PATCH 1017/1444] New translations _category_.json (Japanese) --- .../current/clarity/noteworthy-contracts/_category_.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/_category_.json b/i18n/ja/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/_category_.json index 14b9388b4d..eb32d48e32 100644 --- a/i18n/ja/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/_category_.json +++ b/i18n/ja/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/_category_.json @@ -1,6 +1,6 @@ { "label": "Noteworthy Contracts", - "position": 4, + "position": 5, "link": { "type": "generated-index", "description": "Specific deployed Clarity Contracts worth mentioning." From 41b817131c2d20b5ae373cce17dd4870c9ca0924 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Fri, 28 Apr 2023 01:42:34 +0200 Subject: [PATCH 1018/1444] New translations decidable.md (Japanese) --- .../current/clarity/security/decidable.md | 174 ++++++++++++++++++ 1 file changed, 174 insertions(+) create mode 100644 i18n/ja/docusaurus-plugin-content-docs/current/clarity/security/decidable.md diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/clarity/security/decidable.md b/i18n/ja/docusaurus-plugin-content-docs/current/clarity/security/decidable.md new file mode 100644 index 0000000000..787e017fee --- /dev/null +++ b/i18n/ja/docusaurus-plugin-content-docs/current/clarity/security/decidable.md @@ -0,0 +1,174 @@ +--- +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 in regards to the security advantages of Clarity, but what do they mean? + +While related, they are not quite interchangeable, and there are a few differences. + +### Non-Turing Complete + +A system or language is considered 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, which 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, especially those involving unbounded loops or recursion. 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 that thinking is that it opens up smart contract security to greater human error. 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 will prevent a problem like this. + +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 would force us as developers to think of a better solution to our problem, like 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 greatly 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, and 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. From 45130ad4e80524a729bf30e92f10930f3ec6c921 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Fri, 28 Apr 2023 01:42:35 +0200 Subject: [PATCH 1019/1444] New translations index.md (Japanese) --- .../current/clarity/security/index.md | 22 +++++++++++++++++++ 1 file changed, 22 insertions(+) create mode 100644 i18n/ja/docusaurus-plugin-content-docs/current/clarity/security/index.md diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/clarity/security/index.md b/i18n/ja/docusaurus-plugin-content-docs/current/clarity/security/index.md new file mode 100644 index 0000000000..90aa31abb4 --- /dev/null +++ b/i18n/ja/docusaurus-plugin-content-docs/current/clarity/security/index.md @@ -0,0 +1,22 @@ +--- +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) From 0c711e23bcbe9f8a87d9291e71dac280c40c18f4 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Fri, 28 Apr 2023 01:42:38 +0200 Subject: [PATCH 1020/1444] New translations index.md (Korean) --- i18n/ko/docusaurus-plugin-content-docs/current/clarity/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/i18n/ko/docusaurus-plugin-content-docs/current/clarity/index.md b/i18n/ko/docusaurus-plugin-content-docs/current/clarity/index.md index 903de93a45..fd941bc266 100644 --- a/i18n/ko/docusaurus-plugin-content-docs/current/clarity/index.md +++ b/i18n/ko/docusaurus-plugin-content-docs/current/clarity/index.md @@ -27,7 +27,7 @@ Clarity code is interpreted and committed to the chain exactly as written. Solid ### 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. If you are unsure what this means, let it not worry you for now. The serious advantage of decidability will become more apparent over time. +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 From 86bd00552cf0c5ef56dd413600df93e0d17b7cb7 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Fri, 28 Apr 2023 01:42:38 +0200 Subject: [PATCH 1021/1444] New translations _category_.json (Korean) --- .../current/clarity/noteworthy-contracts/_category_.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/i18n/ko/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/_category_.json b/i18n/ko/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/_category_.json index 14b9388b4d..eb32d48e32 100644 --- a/i18n/ko/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/_category_.json +++ b/i18n/ko/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/_category_.json @@ -1,6 +1,6 @@ { "label": "Noteworthy Contracts", - "position": 4, + "position": 5, "link": { "type": "generated-index", "description": "Specific deployed Clarity Contracts worth mentioning." From 92b60df1cd295b49ca2f0254f3a06e323c2d1c26 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Fri, 28 Apr 2023 01:42:40 +0200 Subject: [PATCH 1022/1444] New translations decidable.md (Korean) --- .../current/clarity/security/decidable.md | 174 ++++++++++++++++++ 1 file changed, 174 insertions(+) create mode 100644 i18n/ko/docusaurus-plugin-content-docs/current/clarity/security/decidable.md diff --git a/i18n/ko/docusaurus-plugin-content-docs/current/clarity/security/decidable.md b/i18n/ko/docusaurus-plugin-content-docs/current/clarity/security/decidable.md new file mode 100644 index 0000000000..787e017fee --- /dev/null +++ b/i18n/ko/docusaurus-plugin-content-docs/current/clarity/security/decidable.md @@ -0,0 +1,174 @@ +--- +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 in regards to the security advantages of Clarity, but what do they mean? + +While related, they are not quite interchangeable, and there are a few differences. + +### Non-Turing Complete + +A system or language is considered 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, which 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, especially those involving unbounded loops or recursion. 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 that thinking is that it opens up smart contract security to greater human error. 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 will prevent a problem like this. + +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 would force us as developers to think of a better solution to our problem, like 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 greatly 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, and 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. From 24f6252b13b7bfb6520557e0dbe0a6946c1ed23a Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Fri, 28 Apr 2023 01:42:41 +0200 Subject: [PATCH 1023/1444] New translations index.md (Korean) --- .../current/clarity/security/index.md | 22 +++++++++++++++++++ 1 file changed, 22 insertions(+) create mode 100644 i18n/ko/docusaurus-plugin-content-docs/current/clarity/security/index.md diff --git a/i18n/ko/docusaurus-plugin-content-docs/current/clarity/security/index.md b/i18n/ko/docusaurus-plugin-content-docs/current/clarity/security/index.md new file mode 100644 index 0000000000..90aa31abb4 --- /dev/null +++ b/i18n/ko/docusaurus-plugin-content-docs/current/clarity/security/index.md @@ -0,0 +1,22 @@ +--- +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) From 68f77c4a1f9d5cff32750331f8dfb464c71db19f Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Fri, 28 Apr 2023 01:42:44 +0200 Subject: [PATCH 1024/1444] New translations index.md (Russian) --- i18n/ru/docusaurus-plugin-content-docs/current/clarity/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/clarity/index.md b/i18n/ru/docusaurus-plugin-content-docs/current/clarity/index.md index 903de93a45..fd941bc266 100644 --- a/i18n/ru/docusaurus-plugin-content-docs/current/clarity/index.md +++ b/i18n/ru/docusaurus-plugin-content-docs/current/clarity/index.md @@ -27,7 +27,7 @@ Clarity code is interpreted and committed to the chain exactly as written. Solid ### 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. If you are unsure what this means, let it not worry you for now. The serious advantage of decidability will become more apparent over time. +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 From c844d07ba1dbd6a59ee000b91d6261762ab34dd7 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Fri, 28 Apr 2023 01:42:44 +0200 Subject: [PATCH 1025/1444] New translations _category_.json (Russian) --- .../current/clarity/noteworthy-contracts/_category_.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/_category_.json b/i18n/ru/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/_category_.json index 14b9388b4d..eb32d48e32 100644 --- a/i18n/ru/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/_category_.json +++ b/i18n/ru/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/_category_.json @@ -1,6 +1,6 @@ { "label": "Noteworthy Contracts", - "position": 4, + "position": 5, "link": { "type": "generated-index", "description": "Specific deployed Clarity Contracts worth mentioning." From 86c87716ab0dcbac15084923f07faf051d2c6916 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Fri, 28 Apr 2023 01:42:45 +0200 Subject: [PATCH 1026/1444] New translations decidable.md (Russian) --- .../current/clarity/security/decidable.md | 174 ++++++++++++++++++ 1 file changed, 174 insertions(+) create mode 100644 i18n/ru/docusaurus-plugin-content-docs/current/clarity/security/decidable.md diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/clarity/security/decidable.md b/i18n/ru/docusaurus-plugin-content-docs/current/clarity/security/decidable.md new file mode 100644 index 0000000000..787e017fee --- /dev/null +++ b/i18n/ru/docusaurus-plugin-content-docs/current/clarity/security/decidable.md @@ -0,0 +1,174 @@ +--- +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 in regards to the security advantages of Clarity, but what do they mean? + +While related, they are not quite interchangeable, and there are a few differences. + +### Non-Turing Complete + +A system or language is considered 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, which 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, especially those involving unbounded loops or recursion. 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 that thinking is that it opens up smart contract security to greater human error. 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 will prevent a problem like this. + +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 would force us as developers to think of a better solution to our problem, like 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 greatly 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, and 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. From 215f21b91cf0506fbaaafb734124633a4c85749e Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Fri, 28 Apr 2023 01:42:46 +0200 Subject: [PATCH 1027/1444] New translations index.md (Russian) --- .../current/clarity/security/index.md | 22 +++++++++++++++++++ 1 file changed, 22 insertions(+) create mode 100644 i18n/ru/docusaurus-plugin-content-docs/current/clarity/security/index.md diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/clarity/security/index.md b/i18n/ru/docusaurus-plugin-content-docs/current/clarity/security/index.md new file mode 100644 index 0000000000..90aa31abb4 --- /dev/null +++ b/i18n/ru/docusaurus-plugin-content-docs/current/clarity/security/index.md @@ -0,0 +1,22 @@ +--- +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) From 8fbd7b3efa157726d215123df0814663fe8ad4f7 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Fri, 28 Apr 2023 01:42:49 +0200 Subject: [PATCH 1028/1444] New translations index.md (Turkish) --- i18n/tr/docusaurus-plugin-content-docs/current/clarity/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/i18n/tr/docusaurus-plugin-content-docs/current/clarity/index.md b/i18n/tr/docusaurus-plugin-content-docs/current/clarity/index.md index 903de93a45..fd941bc266 100644 --- a/i18n/tr/docusaurus-plugin-content-docs/current/clarity/index.md +++ b/i18n/tr/docusaurus-plugin-content-docs/current/clarity/index.md @@ -27,7 +27,7 @@ Clarity code is interpreted and committed to the chain exactly as written. Solid ### 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. If you are unsure what this means, let it not worry you for now. The serious advantage of decidability will become more apparent over time. +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 From a547b48850fc27be3ec4679211ec5887766e0ac2 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Fri, 28 Apr 2023 01:42:50 +0200 Subject: [PATCH 1029/1444] New translations _category_.json (Turkish) --- .../current/clarity/noteworthy-contracts/_category_.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/i18n/tr/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/_category_.json b/i18n/tr/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/_category_.json index 14b9388b4d..eb32d48e32 100644 --- a/i18n/tr/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/_category_.json +++ b/i18n/tr/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/_category_.json @@ -1,6 +1,6 @@ { "label": "Noteworthy Contracts", - "position": 4, + "position": 5, "link": { "type": "generated-index", "description": "Specific deployed Clarity Contracts worth mentioning." From 03ad743336b8b36b3c1081b220730e9795d80935 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Fri, 28 Apr 2023 01:42:51 +0200 Subject: [PATCH 1030/1444] New translations decidable.md (Turkish) --- .../current/clarity/security/decidable.md | 174 ++++++++++++++++++ 1 file changed, 174 insertions(+) create mode 100644 i18n/tr/docusaurus-plugin-content-docs/current/clarity/security/decidable.md diff --git a/i18n/tr/docusaurus-plugin-content-docs/current/clarity/security/decidable.md b/i18n/tr/docusaurus-plugin-content-docs/current/clarity/security/decidable.md new file mode 100644 index 0000000000..787e017fee --- /dev/null +++ b/i18n/tr/docusaurus-plugin-content-docs/current/clarity/security/decidable.md @@ -0,0 +1,174 @@ +--- +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 in regards to the security advantages of Clarity, but what do they mean? + +While related, they are not quite interchangeable, and there are a few differences. + +### Non-Turing Complete + +A system or language is considered 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, which 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, especially those involving unbounded loops or recursion. 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 that thinking is that it opens up smart contract security to greater human error. 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 will prevent a problem like this. + +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 would force us as developers to think of a better solution to our problem, like 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 greatly 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, and 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. From 7e34e290637ecf387ec22a81a666774586507f1d Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Fri, 28 Apr 2023 01:42:52 +0200 Subject: [PATCH 1031/1444] New translations index.md (Turkish) --- .../current/clarity/security/index.md | 22 +++++++++++++++++++ 1 file changed, 22 insertions(+) create mode 100644 i18n/tr/docusaurus-plugin-content-docs/current/clarity/security/index.md diff --git a/i18n/tr/docusaurus-plugin-content-docs/current/clarity/security/index.md b/i18n/tr/docusaurus-plugin-content-docs/current/clarity/security/index.md new file mode 100644 index 0000000000..90aa31abb4 --- /dev/null +++ b/i18n/tr/docusaurus-plugin-content-docs/current/clarity/security/index.md @@ -0,0 +1,22 @@ +--- +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) From 3fd0edc4155de1f94f4fac8823e044d65fc72696 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Fri, 28 Apr 2023 01:42:54 +0200 Subject: [PATCH 1032/1444] New translations index.md (Chinese Simplified) --- i18n/zh/docusaurus-plugin-content-docs/current/clarity/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/clarity/index.md b/i18n/zh/docusaurus-plugin-content-docs/current/clarity/index.md index 0d409aecb4..fd5bcd31c8 100644 --- a/i18n/zh/docusaurus-plugin-content-docs/current/clarity/index.md +++ b/i18n/zh/docusaurus-plugin-content-docs/current/clarity/index.md @@ -27,7 +27,7 @@ Clarity code is interpreted and committed to the chain exactly as written. Solid ### 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. If you are unsure what this means, let it not worry you for now. The serious advantage of decidability will become more apparent over time. +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 From b2b2d24b351e93ba3e336d3f8ce50e292556d6b4 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Fri, 28 Apr 2023 01:42:55 +0200 Subject: [PATCH 1033/1444] New translations _category_.json (Chinese Simplified) --- .../current/clarity/noteworthy-contracts/_category_.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/_category_.json b/i18n/zh/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/_category_.json index 14b9388b4d..eb32d48e32 100644 --- a/i18n/zh/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/_category_.json +++ b/i18n/zh/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/_category_.json @@ -1,6 +1,6 @@ { "label": "Noteworthy Contracts", - "position": 4, + "position": 5, "link": { "type": "generated-index", "description": "Specific deployed Clarity Contracts worth mentioning." From d833db54be63933815d20a8ccf91b28c60895bdb Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Fri, 28 Apr 2023 01:42:56 +0200 Subject: [PATCH 1034/1444] New translations decidable.md (Chinese Simplified) --- .../current/clarity/security/decidable.md | 174 ++++++++++++++++++ 1 file changed, 174 insertions(+) create mode 100644 i18n/zh/docusaurus-plugin-content-docs/current/clarity/security/decidable.md diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/clarity/security/decidable.md b/i18n/zh/docusaurus-plugin-content-docs/current/clarity/security/decidable.md new file mode 100644 index 0000000000..787e017fee --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/current/clarity/security/decidable.md @@ -0,0 +1,174 @@ +--- +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 in regards to the security advantages of Clarity, but what do they mean? + +While related, they are not quite interchangeable, and there are a few differences. + +### Non-Turing Complete + +A system or language is considered 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, which 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, especially those involving unbounded loops or recursion. 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 that thinking is that it opens up smart contract security to greater human error. 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 will prevent a problem like this. + +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 would force us as developers to think of a better solution to our problem, like 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 greatly 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, and 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. From 355dc8b95e0631d76de9710dcac738889d3812fe Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Fri, 28 Apr 2023 01:42:57 +0200 Subject: [PATCH 1035/1444] New translations index.md (Chinese Simplified) --- .../current/clarity/security/index.md | 22 +++++++++++++++++++ 1 file changed, 22 insertions(+) create mode 100644 i18n/zh/docusaurus-plugin-content-docs/current/clarity/security/index.md diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/clarity/security/index.md b/i18n/zh/docusaurus-plugin-content-docs/current/clarity/security/index.md new file mode 100644 index 0000000000..90aa31abb4 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/current/clarity/security/index.md @@ -0,0 +1,22 @@ +--- +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) From 3a2d0190d1fb45878d651dd1fea8e7d09d0a7377 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Fri, 28 Apr 2023 01:42:59 +0200 Subject: [PATCH 1036/1444] New translations index.md (Vietnamese) --- i18n/vi/docusaurus-plugin-content-docs/current/clarity/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/i18n/vi/docusaurus-plugin-content-docs/current/clarity/index.md b/i18n/vi/docusaurus-plugin-content-docs/current/clarity/index.md index 903de93a45..fd941bc266 100644 --- a/i18n/vi/docusaurus-plugin-content-docs/current/clarity/index.md +++ b/i18n/vi/docusaurus-plugin-content-docs/current/clarity/index.md @@ -27,7 +27,7 @@ Clarity code is interpreted and committed to the chain exactly as written. Solid ### 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. If you are unsure what this means, let it not worry you for now. The serious advantage of decidability will become more apparent over time. +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 From 287a7bc4424ba0c68c92414bf340dbddb94804a1 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Fri, 28 Apr 2023 01:43:00 +0200 Subject: [PATCH 1037/1444] New translations _category_.json (Vietnamese) --- .../current/clarity/noteworthy-contracts/_category_.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/i18n/vi/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/_category_.json b/i18n/vi/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/_category_.json index 14b9388b4d..eb32d48e32 100644 --- a/i18n/vi/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/_category_.json +++ b/i18n/vi/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/_category_.json @@ -1,6 +1,6 @@ { "label": "Noteworthy Contracts", - "position": 4, + "position": 5, "link": { "type": "generated-index", "description": "Specific deployed Clarity Contracts worth mentioning." From c1ebe44f91a246aa79eda1336242d6e9237541f5 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Fri, 28 Apr 2023 01:43:01 +0200 Subject: [PATCH 1038/1444] New translations decidable.md (Vietnamese) --- .../current/clarity/security/decidable.md | 174 ++++++++++++++++++ 1 file changed, 174 insertions(+) create mode 100644 i18n/vi/docusaurus-plugin-content-docs/current/clarity/security/decidable.md diff --git a/i18n/vi/docusaurus-plugin-content-docs/current/clarity/security/decidable.md b/i18n/vi/docusaurus-plugin-content-docs/current/clarity/security/decidable.md new file mode 100644 index 0000000000..787e017fee --- /dev/null +++ b/i18n/vi/docusaurus-plugin-content-docs/current/clarity/security/decidable.md @@ -0,0 +1,174 @@ +--- +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 in regards to the security advantages of Clarity, but what do they mean? + +While related, they are not quite interchangeable, and there are a few differences. + +### Non-Turing Complete + +A system or language is considered 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, which 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, especially those involving unbounded loops or recursion. 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 that thinking is that it opens up smart contract security to greater human error. 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 will prevent a problem like this. + +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 would force us as developers to think of a better solution to our problem, like 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 greatly 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, and 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. From 9ba8b90df70975bacef5647b886062f58286db32 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Fri, 28 Apr 2023 01:43:02 +0200 Subject: [PATCH 1039/1444] New translations index.md (Vietnamese) --- .../current/clarity/security/index.md | 22 +++++++++++++++++++ 1 file changed, 22 insertions(+) create mode 100644 i18n/vi/docusaurus-plugin-content-docs/current/clarity/security/index.md diff --git a/i18n/vi/docusaurus-plugin-content-docs/current/clarity/security/index.md b/i18n/vi/docusaurus-plugin-content-docs/current/clarity/security/index.md new file mode 100644 index 0000000000..90aa31abb4 --- /dev/null +++ b/i18n/vi/docusaurus-plugin-content-docs/current/clarity/security/index.md @@ -0,0 +1,22 @@ +--- +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) From 3edda7da5e791c26464e8308f46bf0031eeda89e Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Fri, 28 Apr 2023 01:43:05 +0200 Subject: [PATCH 1040/1444] New translations index.md (Portuguese, Brazilian) --- i18n/pt/docusaurus-plugin-content-docs/current/clarity/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/i18n/pt/docusaurus-plugin-content-docs/current/clarity/index.md b/i18n/pt/docusaurus-plugin-content-docs/current/clarity/index.md index 903de93a45..fd941bc266 100644 --- a/i18n/pt/docusaurus-plugin-content-docs/current/clarity/index.md +++ b/i18n/pt/docusaurus-plugin-content-docs/current/clarity/index.md @@ -27,7 +27,7 @@ Clarity code is interpreted and committed to the chain exactly as written. Solid ### 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. If you are unsure what this means, let it not worry you for now. The serious advantage of decidability will become more apparent over time. +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 From 259064781eea4c3cf8b1d983045f8c82db58419a Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Fri, 28 Apr 2023 01:43:05 +0200 Subject: [PATCH 1041/1444] New translations _category_.json (Portuguese, Brazilian) --- .../current/clarity/noteworthy-contracts/_category_.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/i18n/pt/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/_category_.json b/i18n/pt/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/_category_.json index 14b9388b4d..eb32d48e32 100644 --- a/i18n/pt/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/_category_.json +++ b/i18n/pt/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/_category_.json @@ -1,6 +1,6 @@ { "label": "Noteworthy Contracts", - "position": 4, + "position": 5, "link": { "type": "generated-index", "description": "Specific deployed Clarity Contracts worth mentioning." From bfd3ad2349e0da391dfda48985bfbae57fc04e38 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Fri, 28 Apr 2023 01:43:06 +0200 Subject: [PATCH 1042/1444] New translations decidable.md (Portuguese, Brazilian) --- .../current/clarity/security/decidable.md | 174 ++++++++++++++++++ 1 file changed, 174 insertions(+) create mode 100644 i18n/pt/docusaurus-plugin-content-docs/current/clarity/security/decidable.md diff --git a/i18n/pt/docusaurus-plugin-content-docs/current/clarity/security/decidable.md b/i18n/pt/docusaurus-plugin-content-docs/current/clarity/security/decidable.md new file mode 100644 index 0000000000..787e017fee --- /dev/null +++ b/i18n/pt/docusaurus-plugin-content-docs/current/clarity/security/decidable.md @@ -0,0 +1,174 @@ +--- +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 in regards to the security advantages of Clarity, but what do they mean? + +While related, they are not quite interchangeable, and there are a few differences. + +### Non-Turing Complete + +A system or language is considered 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, which 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, especially those involving unbounded loops or recursion. 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 that thinking is that it opens up smart contract security to greater human error. 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 will prevent a problem like this. + +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 would force us as developers to think of a better solution to our problem, like 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 greatly 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, and 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. From fcac0ccd307ab3ec78084b70724eb5dc0ef56a52 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Fri, 28 Apr 2023 01:43:07 +0200 Subject: [PATCH 1043/1444] New translations index.md (Portuguese, Brazilian) --- .../current/clarity/security/index.md | 22 +++++++++++++++++++ 1 file changed, 22 insertions(+) create mode 100644 i18n/pt/docusaurus-plugin-content-docs/current/clarity/security/index.md diff --git a/i18n/pt/docusaurus-plugin-content-docs/current/clarity/security/index.md b/i18n/pt/docusaurus-plugin-content-docs/current/clarity/security/index.md new file mode 100644 index 0000000000..90aa31abb4 --- /dev/null +++ b/i18n/pt/docusaurus-plugin-content-docs/current/clarity/security/index.md @@ -0,0 +1,22 @@ +--- +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) From 2425e886e332c91667758dbcaa6d620f199be24a Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Fri, 28 Apr 2023 01:43:10 +0200 Subject: [PATCH 1044/1444] New translations index.md (Indonesian) --- i18n/id/docusaurus-plugin-content-docs/current/clarity/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/i18n/id/docusaurus-plugin-content-docs/current/clarity/index.md b/i18n/id/docusaurus-plugin-content-docs/current/clarity/index.md index b51e6f9d8e..0e32377f24 100644 --- a/i18n/id/docusaurus-plugin-content-docs/current/clarity/index.md +++ b/i18n/id/docusaurus-plugin-content-docs/current/clarity/index.md @@ -27,7 +27,7 @@ Clarity code is interpreted and committed to the chain exactly as written. Solid ### 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. If you are unsure what this means, let it not worry you for now. The serious advantage of decidability will become more apparent over time. +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 From 7413cd43f52b45aba3ade782024630c139664a7f Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Fri, 28 Apr 2023 01:43:11 +0200 Subject: [PATCH 1045/1444] New translations _category_.json (Indonesian) --- .../current/clarity/noteworthy-contracts/_category_.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/i18n/id/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/_category_.json b/i18n/id/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/_category_.json index 14b9388b4d..eb32d48e32 100644 --- a/i18n/id/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/_category_.json +++ b/i18n/id/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/_category_.json @@ -1,6 +1,6 @@ { "label": "Noteworthy Contracts", - "position": 4, + "position": 5, "link": { "type": "generated-index", "description": "Specific deployed Clarity Contracts worth mentioning." From c2cde8b46d64cfd7167d1f4f5fed5bd520584b4c Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Fri, 28 Apr 2023 01:43:12 +0200 Subject: [PATCH 1046/1444] New translations decidable.md (Indonesian) --- .../current/clarity/security/decidable.md | 174 ++++++++++++++++++ 1 file changed, 174 insertions(+) create mode 100644 i18n/id/docusaurus-plugin-content-docs/current/clarity/security/decidable.md diff --git a/i18n/id/docusaurus-plugin-content-docs/current/clarity/security/decidable.md b/i18n/id/docusaurus-plugin-content-docs/current/clarity/security/decidable.md new file mode 100644 index 0000000000..787e017fee --- /dev/null +++ b/i18n/id/docusaurus-plugin-content-docs/current/clarity/security/decidable.md @@ -0,0 +1,174 @@ +--- +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 in regards to the security advantages of Clarity, but what do they mean? + +While related, they are not quite interchangeable, and there are a few differences. + +### Non-Turing Complete + +A system or language is considered 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, which 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, especially those involving unbounded loops or recursion. 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 that thinking is that it opens up smart contract security to greater human error. 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 will prevent a problem like this. + +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 would force us as developers to think of a better solution to our problem, like 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 greatly 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, and 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. From ab173d5875a2fa87fca7929b728ae0efb350cbed Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Fri, 28 Apr 2023 01:43:13 +0200 Subject: [PATCH 1047/1444] New translations index.md (Indonesian) --- .../current/clarity/security/index.md | 22 +++++++++++++++++++ 1 file changed, 22 insertions(+) create mode 100644 i18n/id/docusaurus-plugin-content-docs/current/clarity/security/index.md diff --git a/i18n/id/docusaurus-plugin-content-docs/current/clarity/security/index.md b/i18n/id/docusaurus-plugin-content-docs/current/clarity/security/index.md new file mode 100644 index 0000000000..90aa31abb4 --- /dev/null +++ b/i18n/id/docusaurus-plugin-content-docs/current/clarity/security/index.md @@ -0,0 +1,22 @@ +--- +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) From 6e9060d2c86a615cefdf849afa0c62f059aa93d9 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Fri, 28 Apr 2023 01:43:16 +0200 Subject: [PATCH 1048/1444] New translations index.md (Hindi) --- i18n/hi/docusaurus-plugin-content-docs/current/clarity/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/i18n/hi/docusaurus-plugin-content-docs/current/clarity/index.md b/i18n/hi/docusaurus-plugin-content-docs/current/clarity/index.md index 903de93a45..fd941bc266 100644 --- a/i18n/hi/docusaurus-plugin-content-docs/current/clarity/index.md +++ b/i18n/hi/docusaurus-plugin-content-docs/current/clarity/index.md @@ -27,7 +27,7 @@ Clarity code is interpreted and committed to the chain exactly as written. Solid ### 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. If you are unsure what this means, let it not worry you for now. The serious advantage of decidability will become more apparent over time. +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 From 0f520a9d4174061647d3eb659fbb01ece601366d Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Fri, 28 Apr 2023 01:43:17 +0200 Subject: [PATCH 1049/1444] New translations _category_.json (Hindi) --- .../current/clarity/noteworthy-contracts/_category_.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/i18n/hi/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/_category_.json b/i18n/hi/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/_category_.json index 14b9388b4d..eb32d48e32 100644 --- a/i18n/hi/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/_category_.json +++ b/i18n/hi/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/_category_.json @@ -1,6 +1,6 @@ { "label": "Noteworthy Contracts", - "position": 4, + "position": 5, "link": { "type": "generated-index", "description": "Specific deployed Clarity Contracts worth mentioning." From 19ae338a92cdba04368f29199c6b8505e5951bc2 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Fri, 28 Apr 2023 01:43:18 +0200 Subject: [PATCH 1050/1444] New translations decidable.md (Hindi) --- .../current/clarity/security/decidable.md | 174 ++++++++++++++++++ 1 file changed, 174 insertions(+) create mode 100644 i18n/hi/docusaurus-plugin-content-docs/current/clarity/security/decidable.md diff --git a/i18n/hi/docusaurus-plugin-content-docs/current/clarity/security/decidable.md b/i18n/hi/docusaurus-plugin-content-docs/current/clarity/security/decidable.md new file mode 100644 index 0000000000..787e017fee --- /dev/null +++ b/i18n/hi/docusaurus-plugin-content-docs/current/clarity/security/decidable.md @@ -0,0 +1,174 @@ +--- +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 in regards to the security advantages of Clarity, but what do they mean? + +While related, they are not quite interchangeable, and there are a few differences. + +### Non-Turing Complete + +A system or language is considered 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, which 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, especially those involving unbounded loops or recursion. 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 that thinking is that it opens up smart contract security to greater human error. 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 will prevent a problem like this. + +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 would force us as developers to think of a better solution to our problem, like 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 greatly 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, and 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. From acb255ebba928ce43f59b8c6e5c10a616ac6011e Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Fri, 28 Apr 2023 01:43:19 +0200 Subject: [PATCH 1051/1444] New translations index.md (Hindi) --- .../current/clarity/security/index.md | 22 +++++++++++++++++++ 1 file changed, 22 insertions(+) create mode 100644 i18n/hi/docusaurus-plugin-content-docs/current/clarity/security/index.md diff --git a/i18n/hi/docusaurus-plugin-content-docs/current/clarity/security/index.md b/i18n/hi/docusaurus-plugin-content-docs/current/clarity/security/index.md new file mode 100644 index 0000000000..90aa31abb4 --- /dev/null +++ b/i18n/hi/docusaurus-plugin-content-docs/current/clarity/security/index.md @@ -0,0 +1,22 @@ +--- +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) From a890361b2e373ef2ae3d2a4632bca49777720949 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Fri, 28 Apr 2023 03:11:36 +0200 Subject: [PATCH 1052/1444] Update source file index.md --- docs/clarity/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/clarity/index.md b/docs/clarity/index.md index 903de93a45..fd941bc266 100644 --- a/docs/clarity/index.md +++ b/docs/clarity/index.md @@ -27,7 +27,7 @@ Clarity code is interpreted and committed to the chain exactly as written. Solid ### 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. If you are unsure what this means, let it not worry you for now. The serious advantage of decidability will become more apparent over time. +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 From 4e4c5cd060e9768872d9c83901ac7437ed1577b9 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Fri, 28 Apr 2023 03:11:38 +0200 Subject: [PATCH 1053/1444] Update source file decidable.md --- docs/clarity/security/decidable.md | 176 +++++++++++++++++++++++++++++ 1 file changed, 176 insertions(+) create mode 100644 docs/clarity/security/decidable.md diff --git a/docs/clarity/security/decidable.md b/docs/clarity/security/decidable.md new file mode 100644 index 0000000000..818c0a9c55 --- /dev/null +++ b/docs/clarity/security/decidable.md @@ -0,0 +1,176 @@ +--- +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 in regards to the security advantages of Clarity, but what do they mean? + +While related, they are not quite interchangeable, and there are a few differences. + +### Non-Turing Complete + +A system or language is considered 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, which 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, especially those involving unbounded loops or recursion. 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 that thinking is that it opens up smart contract security to greater human error. 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 will prevent a problem like this. + +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 would force us as developers to think of a better solution to our problem, like 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 greatly 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, and 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. From 68a82ceeede72c1287296fc4ce2331cacdc33737 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Fri, 28 Apr 2023 03:11:38 +0200 Subject: [PATCH 1054/1444] Update source file index.md --- docs/clarity/security/index.md | 22 ++++++++++++++++++++++ 1 file changed, 22 insertions(+) create mode 100644 docs/clarity/security/index.md diff --git a/docs/clarity/security/index.md b/docs/clarity/security/index.md new file mode 100644 index 0000000000..90aa31abb4 --- /dev/null +++ b/docs/clarity/security/index.md @@ -0,0 +1,22 @@ +--- +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) From a229b0929731b1bfbbb9fb9b9a1e501584164408 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Fri, 28 Apr 2023 03:11:50 +0200 Subject: [PATCH 1055/1444] Update source file _category_.json --- docs/clarity/noteworthy-contracts/_category_.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/clarity/noteworthy-contracts/_category_.json b/docs/clarity/noteworthy-contracts/_category_.json index 14b9388b4d..eb32d48e32 100644 --- a/docs/clarity/noteworthy-contracts/_category_.json +++ b/docs/clarity/noteworthy-contracts/_category_.json @@ -1,6 +1,6 @@ { "label": "Noteworthy Contracts", - "position": 4, + "position": 5, "link": { "type": "generated-index", "description": "Specific deployed Clarity Contracts worth mentioning." From b9f13cdfa3714d4b1243cf486074938af07d12f8 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Tue, 2 May 2023 20:05:35 +0200 Subject: [PATCH 1056/1444] New translations stacking.md (French) --- .../current/stacks-academy/stacking.md | 38 ++++++++++++++++++- 1 file changed, 36 insertions(+), 2 deletions(-) diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/stacks-academy/stacking.md b/i18n/fr/docusaurus-plugin-content-docs/current/stacks-academy/stacking.md index 545f538ecb..a530bca651 100644 --- a/i18n/fr/docusaurus-plugin-content-docs/current/stacks-academy/stacking.md +++ b/i18n/fr/docusaurus-plugin-content-docs/current/stacks-academy/stacking.md @@ -6,11 +6,45 @@ 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. 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. +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 2.0 network. +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). ::: From 77f35f7facc2830660b327c5b900aaa52e7a7a0b Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Tue, 2 May 2023 20:05:36 +0200 Subject: [PATCH 1057/1444] New translations stacking.md (Spanish) --- .../current/stacks-academy/stacking.md | 38 ++++++++++++++++++- 1 file changed, 36 insertions(+), 2 deletions(-) diff --git a/i18n/es/docusaurus-plugin-content-docs/current/stacks-academy/stacking.md b/i18n/es/docusaurus-plugin-content-docs/current/stacks-academy/stacking.md index 8b931297fa..99723c1638 100644 --- a/i18n/es/docusaurus-plugin-content-docs/current/stacks-academy/stacking.md +++ b/i18n/es/docusaurus-plugin-content-docs/current/stacks-academy/stacking.md @@ -6,11 +6,45 @@ sidebar_position: 11 ## Introducción -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. 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. +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 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. +Stacking es una acción integrada, requerida por el mecanismo de "proof-of-transfer" (PoX). 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). ::: From 6bf67f19b4a6243f6035f5318182477099382c62 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Tue, 2 May 2023 20:05:37 +0200 Subject: [PATCH 1058/1444] New translations stacking.md (German) --- .../current/stacks-academy/stacking.md | 38 ++++++++++++++++++- 1 file changed, 36 insertions(+), 2 deletions(-) diff --git a/i18n/de/docusaurus-plugin-content-docs/current/stacks-academy/stacking.md b/i18n/de/docusaurus-plugin-content-docs/current/stacks-academy/stacking.md index 545f538ecb..a530bca651 100644 --- a/i18n/de/docusaurus-plugin-content-docs/current/stacks-academy/stacking.md +++ b/i18n/de/docusaurus-plugin-content-docs/current/stacks-academy/stacking.md @@ -6,11 +6,45 @@ 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. 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. +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 2.0 network. +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). ::: From 83701ae7e617681845b9b83bf64b000b7d191887 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Tue, 2 May 2023 20:05:38 +0200 Subject: [PATCH 1059/1444] New translations stacking.md (Japanese) --- .../current/stacks-academy/stacking.md | 38 ++++++++++++++++++- 1 file changed, 36 insertions(+), 2 deletions(-) diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/stacks-academy/stacking.md b/i18n/ja/docusaurus-plugin-content-docs/current/stacks-academy/stacking.md index 545f538ecb..a530bca651 100644 --- a/i18n/ja/docusaurus-plugin-content-docs/current/stacks-academy/stacking.md +++ b/i18n/ja/docusaurus-plugin-content-docs/current/stacks-academy/stacking.md @@ -6,11 +6,45 @@ 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. 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. +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 2.0 network. +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). ::: From 864c8ed1a4f51535a60c39fda23018575ed34542 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Tue, 2 May 2023 20:05:39 +0200 Subject: [PATCH 1060/1444] New translations stacking.md (Korean) --- .../current/stacks-academy/stacking.md | 38 ++++++++++++++++++- 1 file changed, 36 insertions(+), 2 deletions(-) diff --git a/i18n/ko/docusaurus-plugin-content-docs/current/stacks-academy/stacking.md b/i18n/ko/docusaurus-plugin-content-docs/current/stacks-academy/stacking.md index 545f538ecb..a530bca651 100644 --- a/i18n/ko/docusaurus-plugin-content-docs/current/stacks-academy/stacking.md +++ b/i18n/ko/docusaurus-plugin-content-docs/current/stacks-academy/stacking.md @@ -6,11 +6,45 @@ 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. 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. +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 2.0 network. +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). ::: From 4fbffa561ed2715f0c4e2a7498768914a7d33a39 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Tue, 2 May 2023 20:05:40 +0200 Subject: [PATCH 1061/1444] New translations stacking.md (Russian) --- .../current/stacks-academy/stacking.md | 38 ++++++++++++++++++- 1 file changed, 36 insertions(+), 2 deletions(-) diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/stacks-academy/stacking.md b/i18n/ru/docusaurus-plugin-content-docs/current/stacks-academy/stacking.md index 545f538ecb..a530bca651 100644 --- a/i18n/ru/docusaurus-plugin-content-docs/current/stacks-academy/stacking.md +++ b/i18n/ru/docusaurus-plugin-content-docs/current/stacks-academy/stacking.md @@ -6,11 +6,45 @@ 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. 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. +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 2.0 network. +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). ::: From 0f4598d8c92e4fc2f809dd298e06ad764a7a8c69 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Tue, 2 May 2023 20:05:41 +0200 Subject: [PATCH 1062/1444] New translations stacking.md (Turkish) --- .../current/stacks-academy/stacking.md | 38 ++++++++++++++++++- 1 file changed, 36 insertions(+), 2 deletions(-) diff --git a/i18n/tr/docusaurus-plugin-content-docs/current/stacks-academy/stacking.md b/i18n/tr/docusaurus-plugin-content-docs/current/stacks-academy/stacking.md index 545f538ecb..a530bca651 100644 --- a/i18n/tr/docusaurus-plugin-content-docs/current/stacks-academy/stacking.md +++ b/i18n/tr/docusaurus-plugin-content-docs/current/stacks-academy/stacking.md @@ -6,11 +6,45 @@ 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. 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. +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 2.0 network. +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). ::: From 43396822fb207e19c630d4a4fecd29d1d4b87828 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Tue, 2 May 2023 20:05:42 +0200 Subject: [PATCH 1063/1444] New translations stacking.md (Chinese Simplified) --- .../current/stacks-academy/stacking.md | 38 ++++++++++++++++++- 1 file changed, 36 insertions(+), 2 deletions(-) diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/stacks-academy/stacking.md b/i18n/zh/docusaurus-plugin-content-docs/current/stacks-academy/stacking.md index b684266d47..b76d072814 100644 --- a/i18n/zh/docusaurus-plugin-content-docs/current/stacks-academy/stacking.md +++ b/i18n/zh/docusaurus-plugin-content-docs/current/stacks-academy/stacking.md @@ -6,11 +6,45 @@ 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. 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. +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. 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. +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). ::: From 20490ad62096f6cc0c8130d984171d297c26bdc2 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Tue, 2 May 2023 20:05:43 +0200 Subject: [PATCH 1064/1444] New translations stacking.md (Vietnamese) --- .../current/stacks-academy/stacking.md | 38 ++++++++++++++++++- 1 file changed, 36 insertions(+), 2 deletions(-) diff --git a/i18n/vi/docusaurus-plugin-content-docs/current/stacks-academy/stacking.md b/i18n/vi/docusaurus-plugin-content-docs/current/stacks-academy/stacking.md index 545f538ecb..a530bca651 100644 --- a/i18n/vi/docusaurus-plugin-content-docs/current/stacks-academy/stacking.md +++ b/i18n/vi/docusaurus-plugin-content-docs/current/stacks-academy/stacking.md @@ -6,11 +6,45 @@ 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. 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. +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 2.0 network. +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). ::: From f2c2685b76983f4fabc2502666b893001d9912e7 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Tue, 2 May 2023 20:05:44 +0200 Subject: [PATCH 1065/1444] New translations stacking.md (Portuguese, Brazilian) --- .../current/stacks-academy/stacking.md | 38 ++++++++++++++++++- 1 file changed, 36 insertions(+), 2 deletions(-) diff --git a/i18n/pt/docusaurus-plugin-content-docs/current/stacks-academy/stacking.md b/i18n/pt/docusaurus-plugin-content-docs/current/stacks-academy/stacking.md index 542b62f70f..20e5d5746e 100644 --- a/i18n/pt/docusaurus-plugin-content-docs/current/stacks-academy/stacking.md +++ b/i18n/pt/docusaurus-plugin-content-docs/current/stacks-academy/stacking.md @@ -6,11 +6,45 @@ 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. 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. +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 2.0 network. +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). ::: From acae831a1daded9d838cb4a1b3e946b188d9e38f Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Tue, 2 May 2023 20:05:45 +0200 Subject: [PATCH 1066/1444] New translations stacking.md (Indonesian) --- .../current/stacks-academy/stacking.md | 38 ++++++++++++++++++- 1 file changed, 36 insertions(+), 2 deletions(-) diff --git a/i18n/id/docusaurus-plugin-content-docs/current/stacks-academy/stacking.md b/i18n/id/docusaurus-plugin-content-docs/current/stacks-academy/stacking.md index fb761601c0..b4b3c6e8db 100644 --- a/i18n/id/docusaurus-plugin-content-docs/current/stacks-academy/stacking.md +++ b/i18n/id/docusaurus-plugin-content-docs/current/stacks-academy/stacking.md @@ -6,11 +6,45 @@ sidebar_position: 11 ## Pengantar -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. 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. +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 merupakan tindakan bawaan, yang diperlukan oleh mekanisme "Proof-of-Transfer" (PoX). Mekanisme PoX dijalankan oleh setiap penambang di jaringan Stacks 2.0. +Stacking merupakan tindakan bawaan, yang diperlukan oleh mekanisme "Proof-of-Transfer" (PoX). 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). ::: From 3f42e973aa47fcc05cdacb0f801e697e57734794 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Tue, 2 May 2023 20:05:46 +0200 Subject: [PATCH 1067/1444] New translations stacking.md (Hindi) --- .../current/stacks-academy/stacking.md | 38 ++++++++++++++++++- 1 file changed, 36 insertions(+), 2 deletions(-) diff --git a/i18n/hi/docusaurus-plugin-content-docs/current/stacks-academy/stacking.md b/i18n/hi/docusaurus-plugin-content-docs/current/stacks-academy/stacking.md index 545f538ecb..a530bca651 100644 --- a/i18n/hi/docusaurus-plugin-content-docs/current/stacks-academy/stacking.md +++ b/i18n/hi/docusaurus-plugin-content-docs/current/stacks-academy/stacking.md @@ -6,11 +6,45 @@ 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. 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. +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 2.0 network. +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). ::: From ec9be80cf7c60f37e04d44b8d1597c1af7b14152 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Thu, 4 May 2023 13:49:27 +0200 Subject: [PATCH 1068/1444] Update source file stacking.md --- docs/stacks-academy/stacking.md | 38 +++++++++++++++++++++++++++++++-- 1 file changed, 36 insertions(+), 2 deletions(-) diff --git a/docs/stacks-academy/stacking.md b/docs/stacks-academy/stacking.md index 60531dfced..5be30ea145 100644 --- a/docs/stacks-academy/stacking.md +++ b/docs/stacks-academy/stacking.md @@ -6,11 +6,45 @@ 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. 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. +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 2.0 network. +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). From 775dedb37ed59f1f239c94e8a98d428b6b4fde36 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sat, 10 Jun 2023 06:54:32 +0200 Subject: [PATCH 1069/1444] New translations decidable.md (French) --- .../current/clarity/security/decidable.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/clarity/security/decidable.md b/i18n/fr/docusaurus-plugin-content-docs/current/clarity/security/decidable.md index 787e017fee..2920f647a7 100644 --- a/i18n/fr/docusaurus-plugin-content-docs/current/clarity/security/decidable.md +++ b/i18n/fr/docusaurus-plugin-content-docs/current/clarity/security/decidable.md @@ -7,15 +7,15 @@ 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 in regards to the security advantages of Clarity, but what do they mean? +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, and there are a few differences. +While related, they are not quite interchangeable, since there are a few differences. ### Non-Turing Complete -A system or language is considered 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, which can simulate any Turing machine. Examples of non-Turing complete systems include finite state machines and some domain-specific languages (like Clarity). +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, especially those involving unbounded loops or recursion. 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. +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 @@ -29,7 +29,7 @@ Before we dive into specifics, let's first set the context and viewpoint we shou 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 that thinking is that it opens up smart contract security to greater human error. If we can preserve functionality while mitigating the chance of human error as much as possible, we should do so. +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? @@ -71,7 +71,7 @@ Solidity allows for unbounded loops, recursion, and dynamic function calls, whic 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 will prevent a problem like this. +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. @@ -85,7 +85,7 @@ Lists, on the other hand, which are iterable, do require the developer to define 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 would force us as developers to think of a better solution to our problem, like implementing a way for users to handle mapping/list element operations themselves, instead of mass operations handled at the contract level. +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. @@ -101,13 +101,13 @@ You can view some more common smart contract vulnerabilities and how they are mi 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 greatly mitigated in Clarity, since there is not chance of a program encountering an unbounded loop. +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, and 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. +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. From ea7d5d2ff9070067b95c8e77990fdfa2b07dd21e Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sat, 10 Jun 2023 06:54:33 +0200 Subject: [PATCH 1070/1444] New translations decidable.md (Spanish) --- .../current/clarity/security/decidable.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/i18n/es/docusaurus-plugin-content-docs/current/clarity/security/decidable.md b/i18n/es/docusaurus-plugin-content-docs/current/clarity/security/decidable.md index 787e017fee..2920f647a7 100644 --- a/i18n/es/docusaurus-plugin-content-docs/current/clarity/security/decidable.md +++ b/i18n/es/docusaurus-plugin-content-docs/current/clarity/security/decidable.md @@ -7,15 +7,15 @@ 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 in regards to the security advantages of Clarity, but what do they mean? +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, and there are a few differences. +While related, they are not quite interchangeable, since there are a few differences. ### Non-Turing Complete -A system or language is considered 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, which can simulate any Turing machine. Examples of non-Turing complete systems include finite state machines and some domain-specific languages (like Clarity). +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, especially those involving unbounded loops or recursion. 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. +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 @@ -29,7 +29,7 @@ Before we dive into specifics, let's first set the context and viewpoint we shou 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 that thinking is that it opens up smart contract security to greater human error. If we can preserve functionality while mitigating the chance of human error as much as possible, we should do so. +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? @@ -71,7 +71,7 @@ Solidity allows for unbounded loops, recursion, and dynamic function calls, whic 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 will prevent a problem like this. +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. @@ -85,7 +85,7 @@ Lists, on the other hand, which are iterable, do require the developer to define 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 would force us as developers to think of a better solution to our problem, like implementing a way for users to handle mapping/list element operations themselves, instead of mass operations handled at the contract level. +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. @@ -101,13 +101,13 @@ You can view some more common smart contract vulnerabilities and how they are mi 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 greatly mitigated in Clarity, since there is not chance of a program encountering an unbounded loop. +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, and 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. +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. From 19acc58a38e77e566ac21c7c7bd83d1ec47a0558 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sat, 10 Jun 2023 06:54:34 +0200 Subject: [PATCH 1071/1444] New translations decidable.md (German) --- .../current/clarity/security/decidable.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/i18n/de/docusaurus-plugin-content-docs/current/clarity/security/decidable.md b/i18n/de/docusaurus-plugin-content-docs/current/clarity/security/decidable.md index 787e017fee..2920f647a7 100644 --- a/i18n/de/docusaurus-plugin-content-docs/current/clarity/security/decidable.md +++ b/i18n/de/docusaurus-plugin-content-docs/current/clarity/security/decidable.md @@ -7,15 +7,15 @@ 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 in regards to the security advantages of Clarity, but what do they mean? +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, and there are a few differences. +While related, they are not quite interchangeable, since there are a few differences. ### Non-Turing Complete -A system or language is considered 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, which can simulate any Turing machine. Examples of non-Turing complete systems include finite state machines and some domain-specific languages (like Clarity). +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, especially those involving unbounded loops or recursion. 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. +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 @@ -29,7 +29,7 @@ Before we dive into specifics, let's first set the context and viewpoint we shou 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 that thinking is that it opens up smart contract security to greater human error. If we can preserve functionality while mitigating the chance of human error as much as possible, we should do so. +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? @@ -71,7 +71,7 @@ Solidity allows for unbounded loops, recursion, and dynamic function calls, whic 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 will prevent a problem like this. +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. @@ -85,7 +85,7 @@ Lists, on the other hand, which are iterable, do require the developer to define 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 would force us as developers to think of a better solution to our problem, like implementing a way for users to handle mapping/list element operations themselves, instead of mass operations handled at the contract level. +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. @@ -101,13 +101,13 @@ You can view some more common smart contract vulnerabilities and how they are mi 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 greatly mitigated in Clarity, since there is not chance of a program encountering an unbounded loop. +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, and 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. +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. From 3a6aced6122596cc0e65ce29c128eb2b4de555e3 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sat, 10 Jun 2023 06:54:35 +0200 Subject: [PATCH 1072/1444] New translations decidable.md (Japanese) --- .../current/clarity/security/decidable.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/clarity/security/decidable.md b/i18n/ja/docusaurus-plugin-content-docs/current/clarity/security/decidable.md index 787e017fee..2920f647a7 100644 --- a/i18n/ja/docusaurus-plugin-content-docs/current/clarity/security/decidable.md +++ b/i18n/ja/docusaurus-plugin-content-docs/current/clarity/security/decidable.md @@ -7,15 +7,15 @@ 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 in regards to the security advantages of Clarity, but what do they mean? +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, and there are a few differences. +While related, they are not quite interchangeable, since there are a few differences. ### Non-Turing Complete -A system or language is considered 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, which can simulate any Turing machine. Examples of non-Turing complete systems include finite state machines and some domain-specific languages (like Clarity). +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, especially those involving unbounded loops or recursion. 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. +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 @@ -29,7 +29,7 @@ Before we dive into specifics, let's first set the context and viewpoint we shou 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 that thinking is that it opens up smart contract security to greater human error. If we can preserve functionality while mitigating the chance of human error as much as possible, we should do so. +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? @@ -71,7 +71,7 @@ Solidity allows for unbounded loops, recursion, and dynamic function calls, whic 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 will prevent a problem like this. +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. @@ -85,7 +85,7 @@ Lists, on the other hand, which are iterable, do require the developer to define 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 would force us as developers to think of a better solution to our problem, like implementing a way for users to handle mapping/list element operations themselves, instead of mass operations handled at the contract level. +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. @@ -101,13 +101,13 @@ You can view some more common smart contract vulnerabilities and how they are mi 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 greatly mitigated in Clarity, since there is not chance of a program encountering an unbounded loop. +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, and 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. +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. From de0f486e005c3d631842128d6b46ae5518b28c46 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sat, 10 Jun 2023 06:54:36 +0200 Subject: [PATCH 1073/1444] New translations decidable.md (Korean) --- .../current/clarity/security/decidable.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/i18n/ko/docusaurus-plugin-content-docs/current/clarity/security/decidable.md b/i18n/ko/docusaurus-plugin-content-docs/current/clarity/security/decidable.md index 787e017fee..2920f647a7 100644 --- a/i18n/ko/docusaurus-plugin-content-docs/current/clarity/security/decidable.md +++ b/i18n/ko/docusaurus-plugin-content-docs/current/clarity/security/decidable.md @@ -7,15 +7,15 @@ 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 in regards to the security advantages of Clarity, but what do they mean? +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, and there are a few differences. +While related, they are not quite interchangeable, since there are a few differences. ### Non-Turing Complete -A system or language is considered 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, which can simulate any Turing machine. Examples of non-Turing complete systems include finite state machines and some domain-specific languages (like Clarity). +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, especially those involving unbounded loops or recursion. 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. +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 @@ -29,7 +29,7 @@ Before we dive into specifics, let's first set the context and viewpoint we shou 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 that thinking is that it opens up smart contract security to greater human error. If we can preserve functionality while mitigating the chance of human error as much as possible, we should do so. +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? @@ -71,7 +71,7 @@ Solidity allows for unbounded loops, recursion, and dynamic function calls, whic 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 will prevent a problem like this. +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. @@ -85,7 +85,7 @@ Lists, on the other hand, which are iterable, do require the developer to define 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 would force us as developers to think of a better solution to our problem, like implementing a way for users to handle mapping/list element operations themselves, instead of mass operations handled at the contract level. +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. @@ -101,13 +101,13 @@ You can view some more common smart contract vulnerabilities and how they are mi 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 greatly mitigated in Clarity, since there is not chance of a program encountering an unbounded loop. +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, and 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. +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. From 62026f35705d7d17a27f10eb375a2f6035f25141 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sat, 10 Jun 2023 06:54:37 +0200 Subject: [PATCH 1074/1444] New translations decidable.md (Russian) --- .../current/clarity/security/decidable.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/clarity/security/decidable.md b/i18n/ru/docusaurus-plugin-content-docs/current/clarity/security/decidable.md index 787e017fee..2920f647a7 100644 --- a/i18n/ru/docusaurus-plugin-content-docs/current/clarity/security/decidable.md +++ b/i18n/ru/docusaurus-plugin-content-docs/current/clarity/security/decidable.md @@ -7,15 +7,15 @@ 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 in regards to the security advantages of Clarity, but what do they mean? +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, and there are a few differences. +While related, they are not quite interchangeable, since there are a few differences. ### Non-Turing Complete -A system or language is considered 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, which can simulate any Turing machine. Examples of non-Turing complete systems include finite state machines and some domain-specific languages (like Clarity). +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, especially those involving unbounded loops or recursion. 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. +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 @@ -29,7 +29,7 @@ Before we dive into specifics, let's first set the context and viewpoint we shou 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 that thinking is that it opens up smart contract security to greater human error. If we can preserve functionality while mitigating the chance of human error as much as possible, we should do so. +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? @@ -71,7 +71,7 @@ Solidity allows for unbounded loops, recursion, and dynamic function calls, whic 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 will prevent a problem like this. +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. @@ -85,7 +85,7 @@ Lists, on the other hand, which are iterable, do require the developer to define 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 would force us as developers to think of a better solution to our problem, like implementing a way for users to handle mapping/list element operations themselves, instead of mass operations handled at the contract level. +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. @@ -101,13 +101,13 @@ You can view some more common smart contract vulnerabilities and how they are mi 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 greatly mitigated in Clarity, since there is not chance of a program encountering an unbounded loop. +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, and 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. +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. From 5a11864e1636335e52cb68e2afd98584fbe4dba1 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sat, 10 Jun 2023 06:54:38 +0200 Subject: [PATCH 1075/1444] New translations decidable.md (Turkish) --- .../current/clarity/security/decidable.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/i18n/tr/docusaurus-plugin-content-docs/current/clarity/security/decidable.md b/i18n/tr/docusaurus-plugin-content-docs/current/clarity/security/decidable.md index 787e017fee..2920f647a7 100644 --- a/i18n/tr/docusaurus-plugin-content-docs/current/clarity/security/decidable.md +++ b/i18n/tr/docusaurus-plugin-content-docs/current/clarity/security/decidable.md @@ -7,15 +7,15 @@ 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 in regards to the security advantages of Clarity, but what do they mean? +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, and there are a few differences. +While related, they are not quite interchangeable, since there are a few differences. ### Non-Turing Complete -A system or language is considered 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, which can simulate any Turing machine. Examples of non-Turing complete systems include finite state machines and some domain-specific languages (like Clarity). +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, especially those involving unbounded loops or recursion. 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. +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 @@ -29,7 +29,7 @@ Before we dive into specifics, let's first set the context and viewpoint we shou 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 that thinking is that it opens up smart contract security to greater human error. If we can preserve functionality while mitigating the chance of human error as much as possible, we should do so. +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? @@ -71,7 +71,7 @@ Solidity allows for unbounded loops, recursion, and dynamic function calls, whic 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 will prevent a problem like this. +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. @@ -85,7 +85,7 @@ Lists, on the other hand, which are iterable, do require the developer to define 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 would force us as developers to think of a better solution to our problem, like implementing a way for users to handle mapping/list element operations themselves, instead of mass operations handled at the contract level. +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. @@ -101,13 +101,13 @@ You can view some more common smart contract vulnerabilities and how they are mi 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 greatly mitigated in Clarity, since there is not chance of a program encountering an unbounded loop. +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, and 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. +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. From 721445dd78f1a66b420ab1c86d90e8cd6698701a Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sat, 10 Jun 2023 06:54:39 +0200 Subject: [PATCH 1076/1444] New translations decidable.md (Chinese Simplified) --- .../current/clarity/security/decidable.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/clarity/security/decidable.md b/i18n/zh/docusaurus-plugin-content-docs/current/clarity/security/decidable.md index 787e017fee..2920f647a7 100644 --- a/i18n/zh/docusaurus-plugin-content-docs/current/clarity/security/decidable.md +++ b/i18n/zh/docusaurus-plugin-content-docs/current/clarity/security/decidable.md @@ -7,15 +7,15 @@ 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 in regards to the security advantages of Clarity, but what do they mean? +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, and there are a few differences. +While related, they are not quite interchangeable, since there are a few differences. ### Non-Turing Complete -A system or language is considered 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, which can simulate any Turing machine. Examples of non-Turing complete systems include finite state machines and some domain-specific languages (like Clarity). +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, especially those involving unbounded loops or recursion. 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. +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 @@ -29,7 +29,7 @@ Before we dive into specifics, let's first set the context and viewpoint we shou 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 that thinking is that it opens up smart contract security to greater human error. If we can preserve functionality while mitigating the chance of human error as much as possible, we should do so. +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? @@ -71,7 +71,7 @@ Solidity allows for unbounded loops, recursion, and dynamic function calls, whic 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 will prevent a problem like this. +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. @@ -85,7 +85,7 @@ Lists, on the other hand, which are iterable, do require the developer to define 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 would force us as developers to think of a better solution to our problem, like implementing a way for users to handle mapping/list element operations themselves, instead of mass operations handled at the contract level. +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. @@ -101,13 +101,13 @@ You can view some more common smart contract vulnerabilities and how they are mi 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 greatly mitigated in Clarity, since there is not chance of a program encountering an unbounded loop. +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, and 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. +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. From 53a9e374645de6e7f85ad2041f2f3efaa91b0361 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sat, 10 Jun 2023 06:54:40 +0200 Subject: [PATCH 1077/1444] New translations decidable.md (Vietnamese) --- .../current/clarity/security/decidable.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/i18n/vi/docusaurus-plugin-content-docs/current/clarity/security/decidable.md b/i18n/vi/docusaurus-plugin-content-docs/current/clarity/security/decidable.md index 787e017fee..2920f647a7 100644 --- a/i18n/vi/docusaurus-plugin-content-docs/current/clarity/security/decidable.md +++ b/i18n/vi/docusaurus-plugin-content-docs/current/clarity/security/decidable.md @@ -7,15 +7,15 @@ 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 in regards to the security advantages of Clarity, but what do they mean? +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, and there are a few differences. +While related, they are not quite interchangeable, since there are a few differences. ### Non-Turing Complete -A system or language is considered 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, which can simulate any Turing machine. Examples of non-Turing complete systems include finite state machines and some domain-specific languages (like Clarity). +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, especially those involving unbounded loops or recursion. 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. +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 @@ -29,7 +29,7 @@ Before we dive into specifics, let's first set the context and viewpoint we shou 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 that thinking is that it opens up smart contract security to greater human error. If we can preserve functionality while mitigating the chance of human error as much as possible, we should do so. +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? @@ -71,7 +71,7 @@ Solidity allows for unbounded loops, recursion, and dynamic function calls, whic 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 will prevent a problem like this. +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. @@ -85,7 +85,7 @@ Lists, on the other hand, which are iterable, do require the developer to define 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 would force us as developers to think of a better solution to our problem, like implementing a way for users to handle mapping/list element operations themselves, instead of mass operations handled at the contract level. +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. @@ -101,13 +101,13 @@ You can view some more common smart contract vulnerabilities and how they are mi 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 greatly mitigated in Clarity, since there is not chance of a program encountering an unbounded loop. +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, and 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. +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. From ceca2b468bf1e7168da603aa6ea3a3a058ca6ae8 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sat, 10 Jun 2023 06:54:41 +0200 Subject: [PATCH 1078/1444] New translations decidable.md (Portuguese, Brazilian) --- .../current/clarity/security/decidable.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/i18n/pt/docusaurus-plugin-content-docs/current/clarity/security/decidable.md b/i18n/pt/docusaurus-plugin-content-docs/current/clarity/security/decidable.md index 787e017fee..2920f647a7 100644 --- a/i18n/pt/docusaurus-plugin-content-docs/current/clarity/security/decidable.md +++ b/i18n/pt/docusaurus-plugin-content-docs/current/clarity/security/decidable.md @@ -7,15 +7,15 @@ 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 in regards to the security advantages of Clarity, but what do they mean? +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, and there are a few differences. +While related, they are not quite interchangeable, since there are a few differences. ### Non-Turing Complete -A system or language is considered 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, which can simulate any Turing machine. Examples of non-Turing complete systems include finite state machines and some domain-specific languages (like Clarity). +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, especially those involving unbounded loops or recursion. 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. +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 @@ -29,7 +29,7 @@ Before we dive into specifics, let's first set the context and viewpoint we shou 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 that thinking is that it opens up smart contract security to greater human error. If we can preserve functionality while mitigating the chance of human error as much as possible, we should do so. +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? @@ -71,7 +71,7 @@ Solidity allows for unbounded loops, recursion, and dynamic function calls, whic 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 will prevent a problem like this. +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. @@ -85,7 +85,7 @@ Lists, on the other hand, which are iterable, do require the developer to define 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 would force us as developers to think of a better solution to our problem, like implementing a way for users to handle mapping/list element operations themselves, instead of mass operations handled at the contract level. +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. @@ -101,13 +101,13 @@ You can view some more common smart contract vulnerabilities and how they are mi 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 greatly mitigated in Clarity, since there is not chance of a program encountering an unbounded loop. +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, and 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. +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. From a889429af6aa3630140f14056c5e4dbab65878fc Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sat, 10 Jun 2023 06:54:42 +0200 Subject: [PATCH 1079/1444] New translations decidable.md (Indonesian) --- .../current/clarity/security/decidable.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/i18n/id/docusaurus-plugin-content-docs/current/clarity/security/decidable.md b/i18n/id/docusaurus-plugin-content-docs/current/clarity/security/decidable.md index 787e017fee..2920f647a7 100644 --- a/i18n/id/docusaurus-plugin-content-docs/current/clarity/security/decidable.md +++ b/i18n/id/docusaurus-plugin-content-docs/current/clarity/security/decidable.md @@ -7,15 +7,15 @@ 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 in regards to the security advantages of Clarity, but what do they mean? +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, and there are a few differences. +While related, they are not quite interchangeable, since there are a few differences. ### Non-Turing Complete -A system or language is considered 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, which can simulate any Turing machine. Examples of non-Turing complete systems include finite state machines and some domain-specific languages (like Clarity). +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, especially those involving unbounded loops or recursion. 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. +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 @@ -29,7 +29,7 @@ Before we dive into specifics, let's first set the context and viewpoint we shou 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 that thinking is that it opens up smart contract security to greater human error. If we can preserve functionality while mitigating the chance of human error as much as possible, we should do so. +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? @@ -71,7 +71,7 @@ Solidity allows for unbounded loops, recursion, and dynamic function calls, whic 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 will prevent a problem like this. +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. @@ -85,7 +85,7 @@ Lists, on the other hand, which are iterable, do require the developer to define 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 would force us as developers to think of a better solution to our problem, like implementing a way for users to handle mapping/list element operations themselves, instead of mass operations handled at the contract level. +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. @@ -101,13 +101,13 @@ You can view some more common smart contract vulnerabilities and how they are mi 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 greatly mitigated in Clarity, since there is not chance of a program encountering an unbounded loop. +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, and 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. +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. From 0b281bc2f10602d6a2ef6891982384126d8bce2e Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sat, 10 Jun 2023 06:54:43 +0200 Subject: [PATCH 1080/1444] New translations decidable.md (Hindi) --- .../current/clarity/security/decidable.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/i18n/hi/docusaurus-plugin-content-docs/current/clarity/security/decidable.md b/i18n/hi/docusaurus-plugin-content-docs/current/clarity/security/decidable.md index 787e017fee..2920f647a7 100644 --- a/i18n/hi/docusaurus-plugin-content-docs/current/clarity/security/decidable.md +++ b/i18n/hi/docusaurus-plugin-content-docs/current/clarity/security/decidable.md @@ -7,15 +7,15 @@ 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 in regards to the security advantages of Clarity, but what do they mean? +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, and there are a few differences. +While related, they are not quite interchangeable, since there are a few differences. ### Non-Turing Complete -A system or language is considered 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, which can simulate any Turing machine. Examples of non-Turing complete systems include finite state machines and some domain-specific languages (like Clarity). +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, especially those involving unbounded loops or recursion. 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. +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 @@ -29,7 +29,7 @@ Before we dive into specifics, let's first set the context and viewpoint we shou 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 that thinking is that it opens up smart contract security to greater human error. If we can preserve functionality while mitigating the chance of human error as much as possible, we should do so. +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? @@ -71,7 +71,7 @@ Solidity allows for unbounded loops, recursion, and dynamic function calls, whic 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 will prevent a problem like this. +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. @@ -85,7 +85,7 @@ Lists, on the other hand, which are iterable, do require the developer to define 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 would force us as developers to think of a better solution to our problem, like implementing a way for users to handle mapping/list element operations themselves, instead of mass operations handled at the contract level. +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. @@ -101,13 +101,13 @@ You can view some more common smart contract vulnerabilities and how they are mi 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 greatly mitigated in Clarity, since there is not chance of a program encountering an unbounded loop. +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, and 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. +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. From 137ef3638980240167c1688b9e521ae47ad6b3e7 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sat, 10 Jun 2023 08:02:53 +0200 Subject: [PATCH 1081/1444] Update source file decidable.md --- docs/clarity/security/decidable.md | 21 ++++++++++++--------- 1 file changed, 12 insertions(+), 9 deletions(-) diff --git a/docs/clarity/security/decidable.md b/docs/clarity/security/decidable.md index 818c0a9c55..7d5411e382 100644 --- a/docs/clarity/security/decidable.md +++ b/docs/clarity/security/decidable.md @@ -7,15 +7,18 @@ 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 in regards to the security advantages of Clarity, but what do they mean? +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, and there are a few differences. +While related, they are not quite interchangeable, since there are a few differences. ### Non-Turing Complete -A system or language is considered 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, which can simulate any Turing machine. Examples of non-Turing complete systems include finite state machines and some domain-specific languages (like Clarity). +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, especially those involving unbounded loops or recursion. 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. +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 @@ -29,7 +32,7 @@ Before we dive into specifics, let's first set the context and viewpoint we shou 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 that thinking is that it opens up smart contract security to greater human error. If we can preserve functionality while mitigating the chance of human error as much as possible, we should do so. +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? @@ -72,7 +75,7 @@ Solidity allows for unbounded loops, recursion, and dynamic function calls, whic 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 will prevent a problem like this. +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. @@ -86,7 +89,7 @@ Lists, on the other hand, which are iterable, do require the developer to define 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 would force us as developers to think of a better solution to our problem, like implementing a way for users to handle mapping/list element operations themselves, instead of mass operations handled at the contract level. +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. @@ -102,13 +105,13 @@ You can view some more common smart contract vulnerabilities and how they are mi 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 greatly mitigated in Clarity, since there is not chance of a program encountering an unbounded loop. +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, and 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. +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. From 9fae62c638f44e802d8c01e0bbaf470871bba921 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sat, 1 Jul 2023 03:26:17 +0200 Subject: [PATCH 1082/1444] New translations index.md (French) --- .../current/cookbook/index.md | 8 ++------ 1 file changed, 2 insertions(+), 6 deletions(-) diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/cookbook/index.md b/i18n/fr/docusaurus-plugin-content-docs/current/cookbook/index.md index a2b0e42eea..4ec214fcf5 100644 --- a/i18n/fr/docusaurus-plugin-content-docs/current/cookbook/index.md +++ b/i18n/fr/docusaurus-plugin-content-docs/current/cookbook/index.md @@ -13,11 +13,9 @@ Got an idea you think would make a good addition? We're always [accepting contri ## Bitcoin Integration -Swapping between Bitcoin and Stacks addresses +Getting a Stacks address from a public key -Swapping between xBTC and BTC - -Verifying a transaction on the BTC chain +[Verifying a transaction on the BTC chain](./verifying-a-btc-tx-was-mined.md) ## DAOs @@ -33,8 +31,6 @@ Creating a BTC-backed DAO treasury Minting an NFT with Bitcoin -Airdropping an NFT to a Bitcoin address - ## Stacking and Mining Simple stacking pool From 4bd605972015275b52c6b93b1c44149be0e350ef Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sat, 1 Jul 2023 03:26:19 +0200 Subject: [PATCH 1083/1444] New translations verifying-a-btc-tx-was-mined.md (French) --- .../cookbook/verifying-a-btc-tx-was-mined.md | 195 ++++++++++++++++++ 1 file changed, 195 insertions(+) create mode 100644 i18n/fr/docusaurus-plugin-content-docs/current/cookbook/verifying-a-btc-tx-was-mined.md diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/cookbook/verifying-a-btc-tx-was-mined.md b/i18n/fr/docusaurus-plugin-content-docs/current/cookbook/verifying-a-btc-tx-was-mined.md new file mode 100644 index 0000000000..fbbdbd98b4 --- /dev/null +++ b/i18n/fr/docusaurus-plugin-content-docs/current/cookbook/verifying-a-btc-tx-was-mined.md @@ -0,0 +1,195 @@ +--- +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); +}; +``` From 6d10055f826f7c809d6274750c99325c1da19291 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sat, 1 Jul 2023 03:26:21 +0200 Subject: [PATCH 1084/1444] New translations index.md (Spanish) --- .../current/cookbook/index.md | 8 ++------ 1 file changed, 2 insertions(+), 6 deletions(-) diff --git a/i18n/es/docusaurus-plugin-content-docs/current/cookbook/index.md b/i18n/es/docusaurus-plugin-content-docs/current/cookbook/index.md index a2b0e42eea..4ec214fcf5 100644 --- a/i18n/es/docusaurus-plugin-content-docs/current/cookbook/index.md +++ b/i18n/es/docusaurus-plugin-content-docs/current/cookbook/index.md @@ -13,11 +13,9 @@ Got an idea you think would make a good addition? We're always [accepting contri ## Bitcoin Integration -Swapping between Bitcoin and Stacks addresses +Getting a Stacks address from a public key -Swapping between xBTC and BTC - -Verifying a transaction on the BTC chain +[Verifying a transaction on the BTC chain](./verifying-a-btc-tx-was-mined.md) ## DAOs @@ -33,8 +31,6 @@ Creating a BTC-backed DAO treasury Minting an NFT with Bitcoin -Airdropping an NFT to a Bitcoin address - ## Stacking and Mining Simple stacking pool From 7939d792e7aa3dbb29a4db2b5a8aa038aac63e1c Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sat, 1 Jul 2023 03:26:23 +0200 Subject: [PATCH 1085/1444] New translations verifying-a-btc-tx-was-mined.md (Spanish) --- .../cookbook/verifying-a-btc-tx-was-mined.md | 195 ++++++++++++++++++ 1 file changed, 195 insertions(+) create mode 100644 i18n/es/docusaurus-plugin-content-docs/current/cookbook/verifying-a-btc-tx-was-mined.md diff --git a/i18n/es/docusaurus-plugin-content-docs/current/cookbook/verifying-a-btc-tx-was-mined.md b/i18n/es/docusaurus-plugin-content-docs/current/cookbook/verifying-a-btc-tx-was-mined.md new file mode 100644 index 0000000000..fbbdbd98b4 --- /dev/null +++ b/i18n/es/docusaurus-plugin-content-docs/current/cookbook/verifying-a-btc-tx-was-mined.md @@ -0,0 +1,195 @@ +--- +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); +}; +``` From 6eb4cc7883100122c484deb84bf2ef42cb24edfc Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sat, 1 Jul 2023 03:26:26 +0200 Subject: [PATCH 1086/1444] New translations index.md (German) --- .../current/cookbook/index.md | 8 ++------ 1 file changed, 2 insertions(+), 6 deletions(-) diff --git a/i18n/de/docusaurus-plugin-content-docs/current/cookbook/index.md b/i18n/de/docusaurus-plugin-content-docs/current/cookbook/index.md index a2b0e42eea..4ec214fcf5 100644 --- a/i18n/de/docusaurus-plugin-content-docs/current/cookbook/index.md +++ b/i18n/de/docusaurus-plugin-content-docs/current/cookbook/index.md @@ -13,11 +13,9 @@ Got an idea you think would make a good addition? We're always [accepting contri ## Bitcoin Integration -Swapping between Bitcoin and Stacks addresses +Getting a Stacks address from a public key -Swapping between xBTC and BTC - -Verifying a transaction on the BTC chain +[Verifying a transaction on the BTC chain](./verifying-a-btc-tx-was-mined.md) ## DAOs @@ -33,8 +31,6 @@ Creating a BTC-backed DAO treasury Minting an NFT with Bitcoin -Airdropping an NFT to a Bitcoin address - ## Stacking and Mining Simple stacking pool From fa9ce99583ecdeb2be852767b68f1a6e96ca55b0 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sat, 1 Jul 2023 03:26:28 +0200 Subject: [PATCH 1087/1444] New translations verifying-a-btc-tx-was-mined.md (German) --- .../cookbook/verifying-a-btc-tx-was-mined.md | 195 ++++++++++++++++++ 1 file changed, 195 insertions(+) create mode 100644 i18n/de/docusaurus-plugin-content-docs/current/cookbook/verifying-a-btc-tx-was-mined.md diff --git a/i18n/de/docusaurus-plugin-content-docs/current/cookbook/verifying-a-btc-tx-was-mined.md b/i18n/de/docusaurus-plugin-content-docs/current/cookbook/verifying-a-btc-tx-was-mined.md new file mode 100644 index 0000000000..fbbdbd98b4 --- /dev/null +++ b/i18n/de/docusaurus-plugin-content-docs/current/cookbook/verifying-a-btc-tx-was-mined.md @@ -0,0 +1,195 @@ +--- +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); +}; +``` From 4c155f9eaba421cbef8e53d075fddbbd6f7c57c4 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sat, 1 Jul 2023 03:26:31 +0200 Subject: [PATCH 1088/1444] New translations index.md (Japanese) --- .../current/cookbook/index.md | 8 ++------ 1 file changed, 2 insertions(+), 6 deletions(-) diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/cookbook/index.md b/i18n/ja/docusaurus-plugin-content-docs/current/cookbook/index.md index a2b0e42eea..4ec214fcf5 100644 --- a/i18n/ja/docusaurus-plugin-content-docs/current/cookbook/index.md +++ b/i18n/ja/docusaurus-plugin-content-docs/current/cookbook/index.md @@ -13,11 +13,9 @@ Got an idea you think would make a good addition? We're always [accepting contri ## Bitcoin Integration -Swapping between Bitcoin and Stacks addresses +Getting a Stacks address from a public key -Swapping between xBTC and BTC - -Verifying a transaction on the BTC chain +[Verifying a transaction on the BTC chain](./verifying-a-btc-tx-was-mined.md) ## DAOs @@ -33,8 +31,6 @@ Creating a BTC-backed DAO treasury Minting an NFT with Bitcoin -Airdropping an NFT to a Bitcoin address - ## Stacking and Mining Simple stacking pool From 59627576f6e4e39f5e3d6e7c34a43fe180d061a9 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sat, 1 Jul 2023 03:26:33 +0200 Subject: [PATCH 1089/1444] New translations verifying-a-btc-tx-was-mined.md (Japanese) --- .../cookbook/verifying-a-btc-tx-was-mined.md | 195 ++++++++++++++++++ 1 file changed, 195 insertions(+) create mode 100644 i18n/ja/docusaurus-plugin-content-docs/current/cookbook/verifying-a-btc-tx-was-mined.md diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/cookbook/verifying-a-btc-tx-was-mined.md b/i18n/ja/docusaurus-plugin-content-docs/current/cookbook/verifying-a-btc-tx-was-mined.md new file mode 100644 index 0000000000..fbbdbd98b4 --- /dev/null +++ b/i18n/ja/docusaurus-plugin-content-docs/current/cookbook/verifying-a-btc-tx-was-mined.md @@ -0,0 +1,195 @@ +--- +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); +}; +``` From dbeb6a618b831f80b7dc505727a5b9449d9b8e90 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sat, 1 Jul 2023 03:26:35 +0200 Subject: [PATCH 1090/1444] New translations index.md (Korean) --- .../current/cookbook/index.md | 8 ++------ 1 file changed, 2 insertions(+), 6 deletions(-) diff --git a/i18n/ko/docusaurus-plugin-content-docs/current/cookbook/index.md b/i18n/ko/docusaurus-plugin-content-docs/current/cookbook/index.md index a2b0e42eea..4ec214fcf5 100644 --- a/i18n/ko/docusaurus-plugin-content-docs/current/cookbook/index.md +++ b/i18n/ko/docusaurus-plugin-content-docs/current/cookbook/index.md @@ -13,11 +13,9 @@ Got an idea you think would make a good addition? We're always [accepting contri ## Bitcoin Integration -Swapping between Bitcoin and Stacks addresses +Getting a Stacks address from a public key -Swapping between xBTC and BTC - -Verifying a transaction on the BTC chain +[Verifying a transaction on the BTC chain](./verifying-a-btc-tx-was-mined.md) ## DAOs @@ -33,8 +31,6 @@ Creating a BTC-backed DAO treasury Minting an NFT with Bitcoin -Airdropping an NFT to a Bitcoin address - ## Stacking and Mining Simple stacking pool From 13f8bb96d1ffa20c31b337d11b761ba84e668c4e Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sat, 1 Jul 2023 03:26:37 +0200 Subject: [PATCH 1091/1444] New translations verifying-a-btc-tx-was-mined.md (Korean) --- .../cookbook/verifying-a-btc-tx-was-mined.md | 195 ++++++++++++++++++ 1 file changed, 195 insertions(+) create mode 100644 i18n/ko/docusaurus-plugin-content-docs/current/cookbook/verifying-a-btc-tx-was-mined.md diff --git a/i18n/ko/docusaurus-plugin-content-docs/current/cookbook/verifying-a-btc-tx-was-mined.md b/i18n/ko/docusaurus-plugin-content-docs/current/cookbook/verifying-a-btc-tx-was-mined.md new file mode 100644 index 0000000000..fbbdbd98b4 --- /dev/null +++ b/i18n/ko/docusaurus-plugin-content-docs/current/cookbook/verifying-a-btc-tx-was-mined.md @@ -0,0 +1,195 @@ +--- +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); +}; +``` From 513856f606fae739e821db9d7025989a65c997f1 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sat, 1 Jul 2023 03:26:40 +0200 Subject: [PATCH 1092/1444] New translations index.md (Russian) --- .../current/cookbook/index.md | 8 ++------ 1 file changed, 2 insertions(+), 6 deletions(-) diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/cookbook/index.md b/i18n/ru/docusaurus-plugin-content-docs/current/cookbook/index.md index a2b0e42eea..4ec214fcf5 100644 --- a/i18n/ru/docusaurus-plugin-content-docs/current/cookbook/index.md +++ b/i18n/ru/docusaurus-plugin-content-docs/current/cookbook/index.md @@ -13,11 +13,9 @@ Got an idea you think would make a good addition? We're always [accepting contri ## Bitcoin Integration -Swapping between Bitcoin and Stacks addresses +Getting a Stacks address from a public key -Swapping between xBTC and BTC - -Verifying a transaction on the BTC chain +[Verifying a transaction on the BTC chain](./verifying-a-btc-tx-was-mined.md) ## DAOs @@ -33,8 +31,6 @@ Creating a BTC-backed DAO treasury Minting an NFT with Bitcoin -Airdropping an NFT to a Bitcoin address - ## Stacking and Mining Simple stacking pool From f9198fb26ac85871edb641b998f491463af28567 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sat, 1 Jul 2023 03:26:43 +0200 Subject: [PATCH 1093/1444] New translations verifying-a-btc-tx-was-mined.md (Russian) --- .../cookbook/verifying-a-btc-tx-was-mined.md | 195 ++++++++++++++++++ 1 file changed, 195 insertions(+) create mode 100644 i18n/ru/docusaurus-plugin-content-docs/current/cookbook/verifying-a-btc-tx-was-mined.md diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/cookbook/verifying-a-btc-tx-was-mined.md b/i18n/ru/docusaurus-plugin-content-docs/current/cookbook/verifying-a-btc-tx-was-mined.md new file mode 100644 index 0000000000..fbbdbd98b4 --- /dev/null +++ b/i18n/ru/docusaurus-plugin-content-docs/current/cookbook/verifying-a-btc-tx-was-mined.md @@ -0,0 +1,195 @@ +--- +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); +}; +``` From f9ccbc864e0991b46e2b99a654a3698d0da4f6b8 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sat, 1 Jul 2023 03:26:45 +0200 Subject: [PATCH 1094/1444] New translations index.md (Turkish) --- .../current/cookbook/index.md | 8 ++------ 1 file changed, 2 insertions(+), 6 deletions(-) diff --git a/i18n/tr/docusaurus-plugin-content-docs/current/cookbook/index.md b/i18n/tr/docusaurus-plugin-content-docs/current/cookbook/index.md index a2b0e42eea..4ec214fcf5 100644 --- a/i18n/tr/docusaurus-plugin-content-docs/current/cookbook/index.md +++ b/i18n/tr/docusaurus-plugin-content-docs/current/cookbook/index.md @@ -13,11 +13,9 @@ Got an idea you think would make a good addition? We're always [accepting contri ## Bitcoin Integration -Swapping between Bitcoin and Stacks addresses +Getting a Stacks address from a public key -Swapping between xBTC and BTC - -Verifying a transaction on the BTC chain +[Verifying a transaction on the BTC chain](./verifying-a-btc-tx-was-mined.md) ## DAOs @@ -33,8 +31,6 @@ Creating a BTC-backed DAO treasury Minting an NFT with Bitcoin -Airdropping an NFT to a Bitcoin address - ## Stacking and Mining Simple stacking pool From c86eee182f8dc05c97e1566b65d71dac410e311b Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sat, 1 Jul 2023 03:26:47 +0200 Subject: [PATCH 1095/1444] New translations verifying-a-btc-tx-was-mined.md (Turkish) --- .../cookbook/verifying-a-btc-tx-was-mined.md | 195 ++++++++++++++++++ 1 file changed, 195 insertions(+) create mode 100644 i18n/tr/docusaurus-plugin-content-docs/current/cookbook/verifying-a-btc-tx-was-mined.md diff --git a/i18n/tr/docusaurus-plugin-content-docs/current/cookbook/verifying-a-btc-tx-was-mined.md b/i18n/tr/docusaurus-plugin-content-docs/current/cookbook/verifying-a-btc-tx-was-mined.md new file mode 100644 index 0000000000..fbbdbd98b4 --- /dev/null +++ b/i18n/tr/docusaurus-plugin-content-docs/current/cookbook/verifying-a-btc-tx-was-mined.md @@ -0,0 +1,195 @@ +--- +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); +}; +``` From 1ac86342a50bce2bf5ca774a9679636b7681b6c6 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sat, 1 Jul 2023 03:26:50 +0200 Subject: [PATCH 1096/1444] New translations index.md (Chinese Simplified) --- .../current/cookbook/index.md | 8 ++------ 1 file changed, 2 insertions(+), 6 deletions(-) diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/cookbook/index.md b/i18n/zh/docusaurus-plugin-content-docs/current/cookbook/index.md index a2b0e42eea..4ec214fcf5 100644 --- a/i18n/zh/docusaurus-plugin-content-docs/current/cookbook/index.md +++ b/i18n/zh/docusaurus-plugin-content-docs/current/cookbook/index.md @@ -13,11 +13,9 @@ Got an idea you think would make a good addition? We're always [accepting contri ## Bitcoin Integration -Swapping between Bitcoin and Stacks addresses +Getting a Stacks address from a public key -Swapping between xBTC and BTC - -Verifying a transaction on the BTC chain +[Verifying a transaction on the BTC chain](./verifying-a-btc-tx-was-mined.md) ## DAOs @@ -33,8 +31,6 @@ Creating a BTC-backed DAO treasury Minting an NFT with Bitcoin -Airdropping an NFT to a Bitcoin address - ## Stacking and Mining Simple stacking pool From 8a9217db75497f78ac11d8b506f11e68213269bd Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sat, 1 Jul 2023 03:26:52 +0200 Subject: [PATCH 1097/1444] New translations verifying-a-btc-tx-was-mined.md (Chinese Simplified) --- .../cookbook/verifying-a-btc-tx-was-mined.md | 195 ++++++++++++++++++ 1 file changed, 195 insertions(+) create mode 100644 i18n/zh/docusaurus-plugin-content-docs/current/cookbook/verifying-a-btc-tx-was-mined.md diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/cookbook/verifying-a-btc-tx-was-mined.md b/i18n/zh/docusaurus-plugin-content-docs/current/cookbook/verifying-a-btc-tx-was-mined.md new file mode 100644 index 0000000000..fbbdbd98b4 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/current/cookbook/verifying-a-btc-tx-was-mined.md @@ -0,0 +1,195 @@ +--- +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); +}; +``` From 0257a9f3345428e9fb0e3f18805c5b1ed528899c Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sat, 1 Jul 2023 03:26:54 +0200 Subject: [PATCH 1098/1444] New translations index.md (Vietnamese) --- .../current/cookbook/index.md | 8 ++------ 1 file changed, 2 insertions(+), 6 deletions(-) diff --git a/i18n/vi/docusaurus-plugin-content-docs/current/cookbook/index.md b/i18n/vi/docusaurus-plugin-content-docs/current/cookbook/index.md index a2b0e42eea..4ec214fcf5 100644 --- a/i18n/vi/docusaurus-plugin-content-docs/current/cookbook/index.md +++ b/i18n/vi/docusaurus-plugin-content-docs/current/cookbook/index.md @@ -13,11 +13,9 @@ Got an idea you think would make a good addition? We're always [accepting contri ## Bitcoin Integration -Swapping between Bitcoin and Stacks addresses +Getting a Stacks address from a public key -Swapping between xBTC and BTC - -Verifying a transaction on the BTC chain +[Verifying a transaction on the BTC chain](./verifying-a-btc-tx-was-mined.md) ## DAOs @@ -33,8 +31,6 @@ Creating a BTC-backed DAO treasury Minting an NFT with Bitcoin -Airdropping an NFT to a Bitcoin address - ## Stacking and Mining Simple stacking pool From df5413ccc4c45d7d5c37a0e2badca942659608ab Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sat, 1 Jul 2023 03:26:56 +0200 Subject: [PATCH 1099/1444] New translations verifying-a-btc-tx-was-mined.md (Vietnamese) --- .../cookbook/verifying-a-btc-tx-was-mined.md | 195 ++++++++++++++++++ 1 file changed, 195 insertions(+) create mode 100644 i18n/vi/docusaurus-plugin-content-docs/current/cookbook/verifying-a-btc-tx-was-mined.md diff --git a/i18n/vi/docusaurus-plugin-content-docs/current/cookbook/verifying-a-btc-tx-was-mined.md b/i18n/vi/docusaurus-plugin-content-docs/current/cookbook/verifying-a-btc-tx-was-mined.md new file mode 100644 index 0000000000..fbbdbd98b4 --- /dev/null +++ b/i18n/vi/docusaurus-plugin-content-docs/current/cookbook/verifying-a-btc-tx-was-mined.md @@ -0,0 +1,195 @@ +--- +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); +}; +``` From 971bfc81e586fd8a63b94779da78fa6ac7b340af Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sat, 1 Jul 2023 03:26:59 +0200 Subject: [PATCH 1100/1444] New translations index.md (Portuguese, Brazilian) --- .../current/cookbook/index.md | 8 ++------ 1 file changed, 2 insertions(+), 6 deletions(-) diff --git a/i18n/pt/docusaurus-plugin-content-docs/current/cookbook/index.md b/i18n/pt/docusaurus-plugin-content-docs/current/cookbook/index.md index a2b0e42eea..4ec214fcf5 100644 --- a/i18n/pt/docusaurus-plugin-content-docs/current/cookbook/index.md +++ b/i18n/pt/docusaurus-plugin-content-docs/current/cookbook/index.md @@ -13,11 +13,9 @@ Got an idea you think would make a good addition? We're always [accepting contri ## Bitcoin Integration -Swapping between Bitcoin and Stacks addresses +Getting a Stacks address from a public key -Swapping between xBTC and BTC - -Verifying a transaction on the BTC chain +[Verifying a transaction on the BTC chain](./verifying-a-btc-tx-was-mined.md) ## DAOs @@ -33,8 +31,6 @@ Creating a BTC-backed DAO treasury Minting an NFT with Bitcoin -Airdropping an NFT to a Bitcoin address - ## Stacking and Mining Simple stacking pool From 9af9b1b011b756e7298d7d33907a303b0f3f0895 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sat, 1 Jul 2023 03:27:01 +0200 Subject: [PATCH 1101/1444] New translations verifying-a-btc-tx-was-mined.md (Portuguese, Brazilian) --- .../cookbook/verifying-a-btc-tx-was-mined.md | 195 ++++++++++++++++++ 1 file changed, 195 insertions(+) create mode 100644 i18n/pt/docusaurus-plugin-content-docs/current/cookbook/verifying-a-btc-tx-was-mined.md diff --git a/i18n/pt/docusaurus-plugin-content-docs/current/cookbook/verifying-a-btc-tx-was-mined.md b/i18n/pt/docusaurus-plugin-content-docs/current/cookbook/verifying-a-btc-tx-was-mined.md new file mode 100644 index 0000000000..fbbdbd98b4 --- /dev/null +++ b/i18n/pt/docusaurus-plugin-content-docs/current/cookbook/verifying-a-btc-tx-was-mined.md @@ -0,0 +1,195 @@ +--- +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); +}; +``` From 9a25a2fa120e3ced423e36ece7da0892b81b3608 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sat, 1 Jul 2023 03:27:03 +0200 Subject: [PATCH 1102/1444] New translations index.md (Indonesian) --- .../current/cookbook/index.md | 8 ++------ 1 file changed, 2 insertions(+), 6 deletions(-) diff --git a/i18n/id/docusaurus-plugin-content-docs/current/cookbook/index.md b/i18n/id/docusaurus-plugin-content-docs/current/cookbook/index.md index d8948d8213..efc08b39d1 100644 --- a/i18n/id/docusaurus-plugin-content-docs/current/cookbook/index.md +++ b/i18n/id/docusaurus-plugin-content-docs/current/cookbook/index.md @@ -13,11 +13,9 @@ Got an idea you think would make a good addition? We're always [accepting contri ## Bitcoin Integration -Swapping between Bitcoin and Stacks addresses +Getting a Stacks address from a public key -Swapping between xBTC and BTC - -Verifying a transaction on the BTC chain +[Verifying a transaction on the BTC chain](./verifying-a-btc-tx-was-mined.md) ## DAOs @@ -33,8 +31,6 @@ Creating a BTC-backed DAO treasury Minting an NFT with Bitcoin -Airdropping an NFT to a Bitcoin address - ## Stacking and Mining Simple stacking pool From cd11eb8e4a4a24392ffd4ccbd6b790d0fb16e276 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sat, 1 Jul 2023 03:27:05 +0200 Subject: [PATCH 1103/1444] New translations verifying-a-btc-tx-was-mined.md (Indonesian) --- .../cookbook/verifying-a-btc-tx-was-mined.md | 195 ++++++++++++++++++ 1 file changed, 195 insertions(+) create mode 100644 i18n/id/docusaurus-plugin-content-docs/current/cookbook/verifying-a-btc-tx-was-mined.md diff --git a/i18n/id/docusaurus-plugin-content-docs/current/cookbook/verifying-a-btc-tx-was-mined.md b/i18n/id/docusaurus-plugin-content-docs/current/cookbook/verifying-a-btc-tx-was-mined.md new file mode 100644 index 0000000000..fbbdbd98b4 --- /dev/null +++ b/i18n/id/docusaurus-plugin-content-docs/current/cookbook/verifying-a-btc-tx-was-mined.md @@ -0,0 +1,195 @@ +--- +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); +}; +``` From 1cacb09de5c1fe6f0217f1d0fa3c5c8a2b21e426 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sat, 1 Jul 2023 03:27:08 +0200 Subject: [PATCH 1104/1444] New translations index.md (Hindi) --- .../current/cookbook/index.md | 8 ++------ 1 file changed, 2 insertions(+), 6 deletions(-) diff --git a/i18n/hi/docusaurus-plugin-content-docs/current/cookbook/index.md b/i18n/hi/docusaurus-plugin-content-docs/current/cookbook/index.md index a2b0e42eea..4ec214fcf5 100644 --- a/i18n/hi/docusaurus-plugin-content-docs/current/cookbook/index.md +++ b/i18n/hi/docusaurus-plugin-content-docs/current/cookbook/index.md @@ -13,11 +13,9 @@ Got an idea you think would make a good addition? We're always [accepting contri ## Bitcoin Integration -Swapping between Bitcoin and Stacks addresses +Getting a Stacks address from a public key -Swapping between xBTC and BTC - -Verifying a transaction on the BTC chain +[Verifying a transaction on the BTC chain](./verifying-a-btc-tx-was-mined.md) ## DAOs @@ -33,8 +31,6 @@ Creating a BTC-backed DAO treasury Minting an NFT with Bitcoin -Airdropping an NFT to a Bitcoin address - ## Stacking and Mining Simple stacking pool From 4186bbf78a99f70b12624983957e4340379fc2e1 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sat, 1 Jul 2023 03:27:10 +0200 Subject: [PATCH 1105/1444] New translations verifying-a-btc-tx-was-mined.md (Hindi) --- .../cookbook/verifying-a-btc-tx-was-mined.md | 195 ++++++++++++++++++ 1 file changed, 195 insertions(+) create mode 100644 i18n/hi/docusaurus-plugin-content-docs/current/cookbook/verifying-a-btc-tx-was-mined.md diff --git a/i18n/hi/docusaurus-plugin-content-docs/current/cookbook/verifying-a-btc-tx-was-mined.md b/i18n/hi/docusaurus-plugin-content-docs/current/cookbook/verifying-a-btc-tx-was-mined.md new file mode 100644 index 0000000000..fbbdbd98b4 --- /dev/null +++ b/i18n/hi/docusaurus-plugin-content-docs/current/cookbook/verifying-a-btc-tx-was-mined.md @@ -0,0 +1,195 @@ +--- +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); +}; +``` From fa7bf3eab1ab16fc8f3ff861df9e0810bafbeb38 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Tue, 4 Jul 2023 18:41:50 +0200 Subject: [PATCH 1106/1444] Update source file index.md --- docs/cookbook/index.md | 8 ++------ 1 file changed, 2 insertions(+), 6 deletions(-) diff --git a/docs/cookbook/index.md b/docs/cookbook/index.md index a2b0e42eea..4ec214fcf5 100644 --- a/docs/cookbook/index.md +++ b/docs/cookbook/index.md @@ -13,11 +13,9 @@ Got an idea you think would make a good addition? We're always [accepting contri ## Bitcoin Integration -Swapping between Bitcoin and Stacks addresses +Getting a Stacks address from a public key -Swapping between xBTC and BTC - -Verifying a transaction on the BTC chain +[Verifying a transaction on the BTC chain](./verifying-a-btc-tx-was-mined.md) ## DAOs @@ -33,8 +31,6 @@ Creating a BTC-backed DAO treasury Minting an NFT with Bitcoin -Airdropping an NFT to a Bitcoin address - ## Stacking and Mining Simple stacking pool From 92d3dc804e0b31261a6371bd211b234dafbecb1b Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Tue, 4 Jul 2023 18:41:51 +0200 Subject: [PATCH 1107/1444] Update source file verifying-a-btc-tx-was-mined.md --- docs/cookbook/verifying-a-btc-tx-was-mined.md | 195 ++++++++++++++++++ 1 file changed, 195 insertions(+) create mode 100644 docs/cookbook/verifying-a-btc-tx-was-mined.md diff --git a/docs/cookbook/verifying-a-btc-tx-was-mined.md b/docs/cookbook/verifying-a-btc-tx-was-mined.md new file mode 100644 index 0000000000..fbbdbd98b4 --- /dev/null +++ b/docs/cookbook/verifying-a-btc-tx-was-mined.md @@ -0,0 +1,195 @@ +--- +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); +}; +``` From b01d6253cd87c98354cdfeff231fc959e0e12440 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Tue, 4 Jul 2023 18:42:14 +0200 Subject: [PATCH 1108/1444] New translations index.md (French) --- .../fr/docusaurus-plugin-content-docs/current/cookbook/index.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/cookbook/index.md b/i18n/fr/docusaurus-plugin-content-docs/current/cookbook/index.md index 4ec214fcf5..6b0eb96f59 100644 --- a/i18n/fr/docusaurus-plugin-content-docs/current/cookbook/index.md +++ b/i18n/fr/docusaurus-plugin-content-docs/current/cookbook/index.md @@ -13,6 +13,8 @@ Got an idea you think would make a good addition? We're always [accepting contri ## 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) From 89c3faecadc0976ac68da231748abf5e3261c7a7 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Tue, 4 Jul 2023 18:42:15 +0200 Subject: [PATCH 1109/1444] New translations index.md (Spanish) --- .../es/docusaurus-plugin-content-docs/current/cookbook/index.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/i18n/es/docusaurus-plugin-content-docs/current/cookbook/index.md b/i18n/es/docusaurus-plugin-content-docs/current/cookbook/index.md index 4ec214fcf5..6b0eb96f59 100644 --- a/i18n/es/docusaurus-plugin-content-docs/current/cookbook/index.md +++ b/i18n/es/docusaurus-plugin-content-docs/current/cookbook/index.md @@ -13,6 +13,8 @@ Got an idea you think would make a good addition? We're always [accepting contri ## 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) From 34eb97aa464cde07f117ac273995fe223eb3db42 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Tue, 4 Jul 2023 18:42:16 +0200 Subject: [PATCH 1110/1444] New translations sending-bitcoin-with-hiro-wallet.md (French) --- .../sending-bitcoin-with-hiro-wallet.md | 38 +++++++++++++++++++ 1 file changed, 38 insertions(+) create mode 100644 i18n/fr/docusaurus-plugin-content-docs/current/cookbook/sending-bitcoin-with-hiro-wallet.md diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/cookbook/sending-bitcoin-with-hiro-wallet.md b/i18n/fr/docusaurus-plugin-content-docs/current/cookbook/sending-bitcoin-with-hiro-wallet.md new file mode 100644 index 0000000000..fda05f7356 --- /dev/null +++ b/i18n/fr/docusaurus-plugin-content-docs/current/cookbook/sending-bitcoin-with-hiro-wallet.md @@ -0,0 +1,38 @@ +--- +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). From 9d8e3a14b8ab567c0ba023ddb046e0aada06cf9f Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Tue, 4 Jul 2023 18:42:17 +0200 Subject: [PATCH 1111/1444] New translations sending-bitcoin-with-hiro-wallet.md (Spanish) --- .../sending-bitcoin-with-hiro-wallet.md | 38 +++++++++++++++++++ 1 file changed, 38 insertions(+) create mode 100644 i18n/es/docusaurus-plugin-content-docs/current/cookbook/sending-bitcoin-with-hiro-wallet.md diff --git a/i18n/es/docusaurus-plugin-content-docs/current/cookbook/sending-bitcoin-with-hiro-wallet.md b/i18n/es/docusaurus-plugin-content-docs/current/cookbook/sending-bitcoin-with-hiro-wallet.md new file mode 100644 index 0000000000..fda05f7356 --- /dev/null +++ b/i18n/es/docusaurus-plugin-content-docs/current/cookbook/sending-bitcoin-with-hiro-wallet.md @@ -0,0 +1,38 @@ +--- +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). From aa9f872a972c026ccfbd933c1a5fd6d28cf974fb Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Tue, 4 Jul 2023 18:42:18 +0200 Subject: [PATCH 1112/1444] New translations index.md (German) --- .../de/docusaurus-plugin-content-docs/current/cookbook/index.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/i18n/de/docusaurus-plugin-content-docs/current/cookbook/index.md b/i18n/de/docusaurus-plugin-content-docs/current/cookbook/index.md index 4ec214fcf5..6b0eb96f59 100644 --- a/i18n/de/docusaurus-plugin-content-docs/current/cookbook/index.md +++ b/i18n/de/docusaurus-plugin-content-docs/current/cookbook/index.md @@ -13,6 +13,8 @@ Got an idea you think would make a good addition? We're always [accepting contri ## 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) From 3da27d4ed0eef5d5842c688b6e56655cf78d1e41 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Tue, 4 Jul 2023 18:42:19 +0200 Subject: [PATCH 1113/1444] New translations index.md (Japanese) --- .../ja/docusaurus-plugin-content-docs/current/cookbook/index.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/cookbook/index.md b/i18n/ja/docusaurus-plugin-content-docs/current/cookbook/index.md index 4ec214fcf5..6b0eb96f59 100644 --- a/i18n/ja/docusaurus-plugin-content-docs/current/cookbook/index.md +++ b/i18n/ja/docusaurus-plugin-content-docs/current/cookbook/index.md @@ -13,6 +13,8 @@ Got an idea you think would make a good addition? We're always [accepting contri ## 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) From 5f4f82b6956380ab0cf3fe685830cdac9e5d8aaf Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Tue, 4 Jul 2023 18:42:20 +0200 Subject: [PATCH 1114/1444] New translations index.md (Korean) --- .../ko/docusaurus-plugin-content-docs/current/cookbook/index.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/i18n/ko/docusaurus-plugin-content-docs/current/cookbook/index.md b/i18n/ko/docusaurus-plugin-content-docs/current/cookbook/index.md index 4ec214fcf5..6b0eb96f59 100644 --- a/i18n/ko/docusaurus-plugin-content-docs/current/cookbook/index.md +++ b/i18n/ko/docusaurus-plugin-content-docs/current/cookbook/index.md @@ -13,6 +13,8 @@ Got an idea you think would make a good addition? We're always [accepting contri ## 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) From f6884b1f20731310861058e89923ef3e7b565929 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Tue, 4 Jul 2023 18:42:21 +0200 Subject: [PATCH 1115/1444] New translations index.md (Russian) --- .../ru/docusaurus-plugin-content-docs/current/cookbook/index.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/cookbook/index.md b/i18n/ru/docusaurus-plugin-content-docs/current/cookbook/index.md index 4ec214fcf5..6b0eb96f59 100644 --- a/i18n/ru/docusaurus-plugin-content-docs/current/cookbook/index.md +++ b/i18n/ru/docusaurus-plugin-content-docs/current/cookbook/index.md @@ -13,6 +13,8 @@ Got an idea you think would make a good addition? We're always [accepting contri ## 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) From fab1816dede7ffc3b9b486392665053746666ad3 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Tue, 4 Jul 2023 18:42:22 +0200 Subject: [PATCH 1116/1444] New translations index.md (Turkish) --- .../tr/docusaurus-plugin-content-docs/current/cookbook/index.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/i18n/tr/docusaurus-plugin-content-docs/current/cookbook/index.md b/i18n/tr/docusaurus-plugin-content-docs/current/cookbook/index.md index 4ec214fcf5..6b0eb96f59 100644 --- a/i18n/tr/docusaurus-plugin-content-docs/current/cookbook/index.md +++ b/i18n/tr/docusaurus-plugin-content-docs/current/cookbook/index.md @@ -13,6 +13,8 @@ Got an idea you think would make a good addition? We're always [accepting contri ## 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) From d942ec8150df820c137c85c27d96decfe04d355d Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Tue, 4 Jul 2023 18:42:23 +0200 Subject: [PATCH 1117/1444] New translations index.md (Chinese Simplified) --- .../zh/docusaurus-plugin-content-docs/current/cookbook/index.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/cookbook/index.md b/i18n/zh/docusaurus-plugin-content-docs/current/cookbook/index.md index 4ec214fcf5..6b0eb96f59 100644 --- a/i18n/zh/docusaurus-plugin-content-docs/current/cookbook/index.md +++ b/i18n/zh/docusaurus-plugin-content-docs/current/cookbook/index.md @@ -13,6 +13,8 @@ Got an idea you think would make a good addition? We're always [accepting contri ## 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) From eae37ca6dbdf90b321462f4ff67f54eb1efad7cc Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Tue, 4 Jul 2023 18:42:24 +0200 Subject: [PATCH 1118/1444] New translations index.md (Vietnamese) --- .../vi/docusaurus-plugin-content-docs/current/cookbook/index.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/i18n/vi/docusaurus-plugin-content-docs/current/cookbook/index.md b/i18n/vi/docusaurus-plugin-content-docs/current/cookbook/index.md index 4ec214fcf5..6b0eb96f59 100644 --- a/i18n/vi/docusaurus-plugin-content-docs/current/cookbook/index.md +++ b/i18n/vi/docusaurus-plugin-content-docs/current/cookbook/index.md @@ -13,6 +13,8 @@ Got an idea you think would make a good addition? We're always [accepting contri ## 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) From ff0bd43467185e06b7ac63dad9cba665574d0d9e Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Tue, 4 Jul 2023 18:42:25 +0200 Subject: [PATCH 1119/1444] New translations index.md (Portuguese, Brazilian) --- .../pt/docusaurus-plugin-content-docs/current/cookbook/index.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/i18n/pt/docusaurus-plugin-content-docs/current/cookbook/index.md b/i18n/pt/docusaurus-plugin-content-docs/current/cookbook/index.md index 4ec214fcf5..6b0eb96f59 100644 --- a/i18n/pt/docusaurus-plugin-content-docs/current/cookbook/index.md +++ b/i18n/pt/docusaurus-plugin-content-docs/current/cookbook/index.md @@ -13,6 +13,8 @@ Got an idea you think would make a good addition? We're always [accepting contri ## 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) From d88766a7ba949f1723431661cab4fc70593ceb06 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Tue, 4 Jul 2023 18:42:26 +0200 Subject: [PATCH 1120/1444] New translations index.md (Indonesian) --- .../id/docusaurus-plugin-content-docs/current/cookbook/index.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/i18n/id/docusaurus-plugin-content-docs/current/cookbook/index.md b/i18n/id/docusaurus-plugin-content-docs/current/cookbook/index.md index efc08b39d1..c01b1b05b3 100644 --- a/i18n/id/docusaurus-plugin-content-docs/current/cookbook/index.md +++ b/i18n/id/docusaurus-plugin-content-docs/current/cookbook/index.md @@ -13,6 +13,8 @@ Got an idea you think would make a good addition? We're always [accepting contri ## 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) From e2222b1e716a50c05e1458247815cc4c9aaa2264 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Tue, 4 Jul 2023 18:42:27 +0200 Subject: [PATCH 1121/1444] New translations index.md (Hindi) --- .../hi/docusaurus-plugin-content-docs/current/cookbook/index.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/i18n/hi/docusaurus-plugin-content-docs/current/cookbook/index.md b/i18n/hi/docusaurus-plugin-content-docs/current/cookbook/index.md index 4ec214fcf5..6b0eb96f59 100644 --- a/i18n/hi/docusaurus-plugin-content-docs/current/cookbook/index.md +++ b/i18n/hi/docusaurus-plugin-content-docs/current/cookbook/index.md @@ -13,6 +13,8 @@ Got an idea you think would make a good addition? We're always [accepting contri ## 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) From 88a97329a4d3b82ef3393385d1dc2d50277d58bd Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Tue, 4 Jul 2023 18:42:28 +0200 Subject: [PATCH 1122/1444] New translations sending-bitcoin-with-hiro-wallet.md (German) --- .../sending-bitcoin-with-hiro-wallet.md | 38 +++++++++++++++++++ 1 file changed, 38 insertions(+) create mode 100644 i18n/de/docusaurus-plugin-content-docs/current/cookbook/sending-bitcoin-with-hiro-wallet.md diff --git a/i18n/de/docusaurus-plugin-content-docs/current/cookbook/sending-bitcoin-with-hiro-wallet.md b/i18n/de/docusaurus-plugin-content-docs/current/cookbook/sending-bitcoin-with-hiro-wallet.md new file mode 100644 index 0000000000..fda05f7356 --- /dev/null +++ b/i18n/de/docusaurus-plugin-content-docs/current/cookbook/sending-bitcoin-with-hiro-wallet.md @@ -0,0 +1,38 @@ +--- +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). From 389299404dbdec9483ee710351d51fda5890ec3b Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Tue, 4 Jul 2023 18:42:29 +0200 Subject: [PATCH 1123/1444] New translations sending-bitcoin-with-hiro-wallet.md (Japanese) --- .../sending-bitcoin-with-hiro-wallet.md | 38 +++++++++++++++++++ 1 file changed, 38 insertions(+) create mode 100644 i18n/ja/docusaurus-plugin-content-docs/current/cookbook/sending-bitcoin-with-hiro-wallet.md diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/cookbook/sending-bitcoin-with-hiro-wallet.md b/i18n/ja/docusaurus-plugin-content-docs/current/cookbook/sending-bitcoin-with-hiro-wallet.md new file mode 100644 index 0000000000..fda05f7356 --- /dev/null +++ b/i18n/ja/docusaurus-plugin-content-docs/current/cookbook/sending-bitcoin-with-hiro-wallet.md @@ -0,0 +1,38 @@ +--- +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). From ce3fdef7e2f82eee4b91486cfa9ac7d61a278ee9 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Tue, 4 Jul 2023 18:42:29 +0200 Subject: [PATCH 1124/1444] New translations sending-bitcoin-with-hiro-wallet.md (Korean) --- .../sending-bitcoin-with-hiro-wallet.md | 38 +++++++++++++++++++ 1 file changed, 38 insertions(+) create mode 100644 i18n/ko/docusaurus-plugin-content-docs/current/cookbook/sending-bitcoin-with-hiro-wallet.md diff --git a/i18n/ko/docusaurus-plugin-content-docs/current/cookbook/sending-bitcoin-with-hiro-wallet.md b/i18n/ko/docusaurus-plugin-content-docs/current/cookbook/sending-bitcoin-with-hiro-wallet.md new file mode 100644 index 0000000000..fda05f7356 --- /dev/null +++ b/i18n/ko/docusaurus-plugin-content-docs/current/cookbook/sending-bitcoin-with-hiro-wallet.md @@ -0,0 +1,38 @@ +--- +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). From 5e40a900c5bd09ae9c668f5599e3b334282704e2 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Tue, 4 Jul 2023 18:42:30 +0200 Subject: [PATCH 1125/1444] New translations sending-bitcoin-with-hiro-wallet.md (Russian) --- .../sending-bitcoin-with-hiro-wallet.md | 38 +++++++++++++++++++ 1 file changed, 38 insertions(+) create mode 100644 i18n/ru/docusaurus-plugin-content-docs/current/cookbook/sending-bitcoin-with-hiro-wallet.md diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/cookbook/sending-bitcoin-with-hiro-wallet.md b/i18n/ru/docusaurus-plugin-content-docs/current/cookbook/sending-bitcoin-with-hiro-wallet.md new file mode 100644 index 0000000000..fda05f7356 --- /dev/null +++ b/i18n/ru/docusaurus-plugin-content-docs/current/cookbook/sending-bitcoin-with-hiro-wallet.md @@ -0,0 +1,38 @@ +--- +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). From b69e5367bd32ce89a10a244f174aabc617999b4e Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Tue, 4 Jul 2023 18:42:31 +0200 Subject: [PATCH 1126/1444] New translations sending-bitcoin-with-hiro-wallet.md (Turkish) --- .../sending-bitcoin-with-hiro-wallet.md | 38 +++++++++++++++++++ 1 file changed, 38 insertions(+) create mode 100644 i18n/tr/docusaurus-plugin-content-docs/current/cookbook/sending-bitcoin-with-hiro-wallet.md diff --git a/i18n/tr/docusaurus-plugin-content-docs/current/cookbook/sending-bitcoin-with-hiro-wallet.md b/i18n/tr/docusaurus-plugin-content-docs/current/cookbook/sending-bitcoin-with-hiro-wallet.md new file mode 100644 index 0000000000..fda05f7356 --- /dev/null +++ b/i18n/tr/docusaurus-plugin-content-docs/current/cookbook/sending-bitcoin-with-hiro-wallet.md @@ -0,0 +1,38 @@ +--- +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). From 1f7a7bbf5144e8d6c82309b9390108f318666f41 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Tue, 4 Jul 2023 18:42:32 +0200 Subject: [PATCH 1127/1444] New translations sending-bitcoin-with-hiro-wallet.md (Chinese Simplified) --- .../sending-bitcoin-with-hiro-wallet.md | 38 +++++++++++++++++++ 1 file changed, 38 insertions(+) create mode 100644 i18n/zh/docusaurus-plugin-content-docs/current/cookbook/sending-bitcoin-with-hiro-wallet.md diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/cookbook/sending-bitcoin-with-hiro-wallet.md b/i18n/zh/docusaurus-plugin-content-docs/current/cookbook/sending-bitcoin-with-hiro-wallet.md new file mode 100644 index 0000000000..fda05f7356 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/current/cookbook/sending-bitcoin-with-hiro-wallet.md @@ -0,0 +1,38 @@ +--- +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). From 873f2da3f2186a48e513fee36693bdf5ddfb4ed6 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Tue, 4 Jul 2023 18:42:33 +0200 Subject: [PATCH 1128/1444] New translations sending-bitcoin-with-hiro-wallet.md (Vietnamese) --- .../sending-bitcoin-with-hiro-wallet.md | 38 +++++++++++++++++++ 1 file changed, 38 insertions(+) create mode 100644 i18n/vi/docusaurus-plugin-content-docs/current/cookbook/sending-bitcoin-with-hiro-wallet.md diff --git a/i18n/vi/docusaurus-plugin-content-docs/current/cookbook/sending-bitcoin-with-hiro-wallet.md b/i18n/vi/docusaurus-plugin-content-docs/current/cookbook/sending-bitcoin-with-hiro-wallet.md new file mode 100644 index 0000000000..fda05f7356 --- /dev/null +++ b/i18n/vi/docusaurus-plugin-content-docs/current/cookbook/sending-bitcoin-with-hiro-wallet.md @@ -0,0 +1,38 @@ +--- +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). From 36fa546c70fea379659887e5820157edd69e0b4f Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Tue, 4 Jul 2023 18:42:34 +0200 Subject: [PATCH 1129/1444] New translations sending-bitcoin-with-hiro-wallet.md (Portuguese, Brazilian) --- .../sending-bitcoin-with-hiro-wallet.md | 38 +++++++++++++++++++ 1 file changed, 38 insertions(+) create mode 100644 i18n/pt/docusaurus-plugin-content-docs/current/cookbook/sending-bitcoin-with-hiro-wallet.md diff --git a/i18n/pt/docusaurus-plugin-content-docs/current/cookbook/sending-bitcoin-with-hiro-wallet.md b/i18n/pt/docusaurus-plugin-content-docs/current/cookbook/sending-bitcoin-with-hiro-wallet.md new file mode 100644 index 0000000000..fda05f7356 --- /dev/null +++ b/i18n/pt/docusaurus-plugin-content-docs/current/cookbook/sending-bitcoin-with-hiro-wallet.md @@ -0,0 +1,38 @@ +--- +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). From c97cb9667ec32a1c146601efc253fdb84176db3b Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Tue, 4 Jul 2023 18:42:35 +0200 Subject: [PATCH 1130/1444] New translations sending-bitcoin-with-hiro-wallet.md (Indonesian) --- .../sending-bitcoin-with-hiro-wallet.md | 38 +++++++++++++++++++ 1 file changed, 38 insertions(+) create mode 100644 i18n/id/docusaurus-plugin-content-docs/current/cookbook/sending-bitcoin-with-hiro-wallet.md diff --git a/i18n/id/docusaurus-plugin-content-docs/current/cookbook/sending-bitcoin-with-hiro-wallet.md b/i18n/id/docusaurus-plugin-content-docs/current/cookbook/sending-bitcoin-with-hiro-wallet.md new file mode 100644 index 0000000000..fda05f7356 --- /dev/null +++ b/i18n/id/docusaurus-plugin-content-docs/current/cookbook/sending-bitcoin-with-hiro-wallet.md @@ -0,0 +1,38 @@ +--- +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). From b25b1e05bbe3992f31a40d1dab55b69d2063ba05 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Tue, 4 Jul 2023 18:42:36 +0200 Subject: [PATCH 1131/1444] New translations sending-bitcoin-with-hiro-wallet.md (Hindi) --- .../sending-bitcoin-with-hiro-wallet.md | 38 +++++++++++++++++++ 1 file changed, 38 insertions(+) create mode 100644 i18n/hi/docusaurus-plugin-content-docs/current/cookbook/sending-bitcoin-with-hiro-wallet.md diff --git a/i18n/hi/docusaurus-plugin-content-docs/current/cookbook/sending-bitcoin-with-hiro-wallet.md b/i18n/hi/docusaurus-plugin-content-docs/current/cookbook/sending-bitcoin-with-hiro-wallet.md new file mode 100644 index 0000000000..fda05f7356 --- /dev/null +++ b/i18n/hi/docusaurus-plugin-content-docs/current/cookbook/sending-bitcoin-with-hiro-wallet.md @@ -0,0 +1,38 @@ +--- +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). From a54bcc8814349ad26a674877414d1356e34fd90d Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Tue, 4 Jul 2023 23:56:18 +0200 Subject: [PATCH 1132/1444] Update source file index.md --- docs/cookbook/index.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/cookbook/index.md b/docs/cookbook/index.md index 4ec214fcf5..6b0eb96f59 100644 --- a/docs/cookbook/index.md +++ b/docs/cookbook/index.md @@ -13,6 +13,8 @@ Got an idea you think would make a good addition? We're always [accepting contri ## 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) From 843ce79d3e78cefe3458fba89f29f662528b93e6 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Tue, 4 Jul 2023 23:56:19 +0200 Subject: [PATCH 1133/1444] Update source file sending-bitcoin-with-hiro-wallet.md --- .../sending-bitcoin-with-hiro-wallet.md | 38 +++++++++++++++++++ 1 file changed, 38 insertions(+) create mode 100644 docs/cookbook/sending-bitcoin-with-hiro-wallet.md diff --git a/docs/cookbook/sending-bitcoin-with-hiro-wallet.md b/docs/cookbook/sending-bitcoin-with-hiro-wallet.md new file mode 100644 index 0000000000..fda05f7356 --- /dev/null +++ b/docs/cookbook/sending-bitcoin-with-hiro-wallet.md @@ -0,0 +1,38 @@ +--- +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). From 0589c40581cc221ef5b5cd4e14cb7e821e3b5ef4 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Tue, 4 Jul 2023 23:56:40 +0200 Subject: [PATCH 1134/1444] New translations index.md (French) --- .../current/cookbook/index.md | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/cookbook/index.md b/i18n/fr/docusaurus-plugin-content-docs/current/cookbook/index.md index 6b0eb96f59..9a40e62b46 100644 --- a/i18n/fr/docusaurus-plugin-content-docs/current/cookbook/index.md +++ b/i18n/fr/docusaurus-plugin-content-docs/current/cookbook/index.md @@ -19,6 +19,10 @@ 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 @@ -43,10 +47,6 @@ Simple mining pool Proof of PoX payout -## Oracles - -Creating a simple BTC price oracle - ## Frontend [Post conditions with Stacks.js](./post-conditions) @@ -55,6 +55,8 @@ Creating a simple BTC price oracle [Sending transactions with Stacks.js](./stacks-js-sending-transactions) +Authenticating with Sign in with Stacks + ## Complete Apps [Sup](https://github.com/kenrogers/sup) From c8a74e438d7d06e37e7b7284e7e4f451f7fca59c Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Tue, 4 Jul 2023 23:56:42 +0200 Subject: [PATCH 1135/1444] New translations index.md (Spanish) --- .../current/cookbook/index.md | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/i18n/es/docusaurus-plugin-content-docs/current/cookbook/index.md b/i18n/es/docusaurus-plugin-content-docs/current/cookbook/index.md index 6b0eb96f59..9a40e62b46 100644 --- a/i18n/es/docusaurus-plugin-content-docs/current/cookbook/index.md +++ b/i18n/es/docusaurus-plugin-content-docs/current/cookbook/index.md @@ -19,6 +19,10 @@ 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 @@ -43,10 +47,6 @@ Simple mining pool Proof of PoX payout -## Oracles - -Creating a simple BTC price oracle - ## Frontend [Post conditions with Stacks.js](./post-conditions) @@ -55,6 +55,8 @@ Creating a simple BTC price oracle [Sending transactions with Stacks.js](./stacks-js-sending-transactions) +Authenticating with Sign in with Stacks + ## Complete Apps [Sup](https://github.com/kenrogers/sup) From d1a0db79b1f87cb10180a0501a90a514198f7db4 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Tue, 4 Jul 2023 23:56:43 +0200 Subject: [PATCH 1136/1444] New translations index.md (German) --- .../current/cookbook/index.md | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/i18n/de/docusaurus-plugin-content-docs/current/cookbook/index.md b/i18n/de/docusaurus-plugin-content-docs/current/cookbook/index.md index 6b0eb96f59..9a40e62b46 100644 --- a/i18n/de/docusaurus-plugin-content-docs/current/cookbook/index.md +++ b/i18n/de/docusaurus-plugin-content-docs/current/cookbook/index.md @@ -19,6 +19,10 @@ 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 @@ -43,10 +47,6 @@ Simple mining pool Proof of PoX payout -## Oracles - -Creating a simple BTC price oracle - ## Frontend [Post conditions with Stacks.js](./post-conditions) @@ -55,6 +55,8 @@ Creating a simple BTC price oracle [Sending transactions with Stacks.js](./stacks-js-sending-transactions) +Authenticating with Sign in with Stacks + ## Complete Apps [Sup](https://github.com/kenrogers/sup) From 81d444e479fcd3ae0b766b874364805babc17902 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Tue, 4 Jul 2023 23:56:45 +0200 Subject: [PATCH 1137/1444] New translations index.md (Japanese) --- .../current/cookbook/index.md | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/cookbook/index.md b/i18n/ja/docusaurus-plugin-content-docs/current/cookbook/index.md index 6b0eb96f59..9a40e62b46 100644 --- a/i18n/ja/docusaurus-plugin-content-docs/current/cookbook/index.md +++ b/i18n/ja/docusaurus-plugin-content-docs/current/cookbook/index.md @@ -19,6 +19,10 @@ 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 @@ -43,10 +47,6 @@ Simple mining pool Proof of PoX payout -## Oracles - -Creating a simple BTC price oracle - ## Frontend [Post conditions with Stacks.js](./post-conditions) @@ -55,6 +55,8 @@ Creating a simple BTC price oracle [Sending transactions with Stacks.js](./stacks-js-sending-transactions) +Authenticating with Sign in with Stacks + ## Complete Apps [Sup](https://github.com/kenrogers/sup) From c5ea573c8088c3d3c8e122ed71d8a907c780f93b Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Tue, 4 Jul 2023 23:56:46 +0200 Subject: [PATCH 1138/1444] New translations index.md (Korean) --- .../current/cookbook/index.md | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/i18n/ko/docusaurus-plugin-content-docs/current/cookbook/index.md b/i18n/ko/docusaurus-plugin-content-docs/current/cookbook/index.md index 6b0eb96f59..9a40e62b46 100644 --- a/i18n/ko/docusaurus-plugin-content-docs/current/cookbook/index.md +++ b/i18n/ko/docusaurus-plugin-content-docs/current/cookbook/index.md @@ -19,6 +19,10 @@ 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 @@ -43,10 +47,6 @@ Simple mining pool Proof of PoX payout -## Oracles - -Creating a simple BTC price oracle - ## Frontend [Post conditions with Stacks.js](./post-conditions) @@ -55,6 +55,8 @@ Creating a simple BTC price oracle [Sending transactions with Stacks.js](./stacks-js-sending-transactions) +Authenticating with Sign in with Stacks + ## Complete Apps [Sup](https://github.com/kenrogers/sup) From e3681b50534e07bc26f1b2ca218875ac3e15f68b Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Tue, 4 Jul 2023 23:56:48 +0200 Subject: [PATCH 1139/1444] New translations index.md (Russian) --- .../current/cookbook/index.md | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/cookbook/index.md b/i18n/ru/docusaurus-plugin-content-docs/current/cookbook/index.md index 6b0eb96f59..9a40e62b46 100644 --- a/i18n/ru/docusaurus-plugin-content-docs/current/cookbook/index.md +++ b/i18n/ru/docusaurus-plugin-content-docs/current/cookbook/index.md @@ -19,6 +19,10 @@ 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 @@ -43,10 +47,6 @@ Simple mining pool Proof of PoX payout -## Oracles - -Creating a simple BTC price oracle - ## Frontend [Post conditions with Stacks.js](./post-conditions) @@ -55,6 +55,8 @@ Creating a simple BTC price oracle [Sending transactions with Stacks.js](./stacks-js-sending-transactions) +Authenticating with Sign in with Stacks + ## Complete Apps [Sup](https://github.com/kenrogers/sup) From 20253701a2e3e113a06bf3ee7008de75cc1ae530 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Tue, 4 Jul 2023 23:56:49 +0200 Subject: [PATCH 1140/1444] New translations index.md (Turkish) --- .../current/cookbook/index.md | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/i18n/tr/docusaurus-plugin-content-docs/current/cookbook/index.md b/i18n/tr/docusaurus-plugin-content-docs/current/cookbook/index.md index 6b0eb96f59..9a40e62b46 100644 --- a/i18n/tr/docusaurus-plugin-content-docs/current/cookbook/index.md +++ b/i18n/tr/docusaurus-plugin-content-docs/current/cookbook/index.md @@ -19,6 +19,10 @@ 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 @@ -43,10 +47,6 @@ Simple mining pool Proof of PoX payout -## Oracles - -Creating a simple BTC price oracle - ## Frontend [Post conditions with Stacks.js](./post-conditions) @@ -55,6 +55,8 @@ Creating a simple BTC price oracle [Sending transactions with Stacks.js](./stacks-js-sending-transactions) +Authenticating with Sign in with Stacks + ## Complete Apps [Sup](https://github.com/kenrogers/sup) From fe9c84147f16100ed86dde95eeaa2481a386d9b9 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Tue, 4 Jul 2023 23:56:51 +0200 Subject: [PATCH 1141/1444] New translations index.md (Chinese Simplified) --- .../current/cookbook/index.md | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/cookbook/index.md b/i18n/zh/docusaurus-plugin-content-docs/current/cookbook/index.md index 6b0eb96f59..9a40e62b46 100644 --- a/i18n/zh/docusaurus-plugin-content-docs/current/cookbook/index.md +++ b/i18n/zh/docusaurus-plugin-content-docs/current/cookbook/index.md @@ -19,6 +19,10 @@ 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 @@ -43,10 +47,6 @@ Simple mining pool Proof of PoX payout -## Oracles - -Creating a simple BTC price oracle - ## Frontend [Post conditions with Stacks.js](./post-conditions) @@ -55,6 +55,8 @@ Creating a simple BTC price oracle [Sending transactions with Stacks.js](./stacks-js-sending-transactions) +Authenticating with Sign in with Stacks + ## Complete Apps [Sup](https://github.com/kenrogers/sup) From f4866dce3be5bf619919935197f35dd249a0902d Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Tue, 4 Jul 2023 23:56:52 +0200 Subject: [PATCH 1142/1444] New translations index.md (Vietnamese) --- .../current/cookbook/index.md | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/i18n/vi/docusaurus-plugin-content-docs/current/cookbook/index.md b/i18n/vi/docusaurus-plugin-content-docs/current/cookbook/index.md index 6b0eb96f59..9a40e62b46 100644 --- a/i18n/vi/docusaurus-plugin-content-docs/current/cookbook/index.md +++ b/i18n/vi/docusaurus-plugin-content-docs/current/cookbook/index.md @@ -19,6 +19,10 @@ 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 @@ -43,10 +47,6 @@ Simple mining pool Proof of PoX payout -## Oracles - -Creating a simple BTC price oracle - ## Frontend [Post conditions with Stacks.js](./post-conditions) @@ -55,6 +55,8 @@ Creating a simple BTC price oracle [Sending transactions with Stacks.js](./stacks-js-sending-transactions) +Authenticating with Sign in with Stacks + ## Complete Apps [Sup](https://github.com/kenrogers/sup) From 6dd8df60a7c9d3de2d46b62b92ca0b4a7d5a8fc5 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Tue, 4 Jul 2023 23:56:54 +0200 Subject: [PATCH 1143/1444] New translations index.md (Portuguese, Brazilian) --- .../current/cookbook/index.md | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/i18n/pt/docusaurus-plugin-content-docs/current/cookbook/index.md b/i18n/pt/docusaurus-plugin-content-docs/current/cookbook/index.md index 6b0eb96f59..9a40e62b46 100644 --- a/i18n/pt/docusaurus-plugin-content-docs/current/cookbook/index.md +++ b/i18n/pt/docusaurus-plugin-content-docs/current/cookbook/index.md @@ -19,6 +19,10 @@ 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 @@ -43,10 +47,6 @@ Simple mining pool Proof of PoX payout -## Oracles - -Creating a simple BTC price oracle - ## Frontend [Post conditions with Stacks.js](./post-conditions) @@ -55,6 +55,8 @@ Creating a simple BTC price oracle [Sending transactions with Stacks.js](./stacks-js-sending-transactions) +Authenticating with Sign in with Stacks + ## Complete Apps [Sup](https://github.com/kenrogers/sup) From b40e128f6612883849a26bfaad31304f3f5f9862 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Tue, 4 Jul 2023 23:56:56 +0200 Subject: [PATCH 1144/1444] New translations index.md (Indonesian) --- .../current/cookbook/index.md | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/i18n/id/docusaurus-plugin-content-docs/current/cookbook/index.md b/i18n/id/docusaurus-plugin-content-docs/current/cookbook/index.md index c01b1b05b3..699f8a1dcc 100644 --- a/i18n/id/docusaurus-plugin-content-docs/current/cookbook/index.md +++ b/i18n/id/docusaurus-plugin-content-docs/current/cookbook/index.md @@ -19,6 +19,10 @@ 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 @@ -43,10 +47,6 @@ Simple mining pool Proof of PoX payout -## Oracles - -Creating a simple BTC price oracle - ## Frontend [Post conditions with Stacks.js](./post-conditions) @@ -55,6 +55,8 @@ Creating a simple BTC price oracle [Sending transactions with Stacks.js](./stacks-js-sending-transactions) +Authenticating with Sign in with Stacks + ## Complete Apps [Sup](https://github.com/kenrogers/sup) From 01d606eefd74486a8a6f87f2989229433f1ad11d Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Tue, 4 Jul 2023 23:56:57 +0200 Subject: [PATCH 1145/1444] New translations index.md (Hindi) --- .../current/cookbook/index.md | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/i18n/hi/docusaurus-plugin-content-docs/current/cookbook/index.md b/i18n/hi/docusaurus-plugin-content-docs/current/cookbook/index.md index 6b0eb96f59..9a40e62b46 100644 --- a/i18n/hi/docusaurus-plugin-content-docs/current/cookbook/index.md +++ b/i18n/hi/docusaurus-plugin-content-docs/current/cookbook/index.md @@ -19,6 +19,10 @@ 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 @@ -43,10 +47,6 @@ Simple mining pool Proof of PoX payout -## Oracles - -Creating a simple BTC price oracle - ## Frontend [Post conditions with Stacks.js](./post-conditions) @@ -55,6 +55,8 @@ Creating a simple BTC price oracle [Sending transactions with Stacks.js](./stacks-js-sending-transactions) +Authenticating with Sign in with Stacks + ## Complete Apps [Sup](https://github.com/kenrogers/sup) From 1c9135f917dcbcc692bac86310a35080c12c771c Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Tue, 4 Jul 2023 23:56:58 +0200 Subject: [PATCH 1146/1444] New translations parse-a-btc-tx.md (French) --- .../current/cookbook/parse-a-btc-tx.md | 53 +++++++++++++++++++ 1 file changed, 53 insertions(+) create mode 100644 i18n/fr/docusaurus-plugin-content-docs/current/cookbook/parse-a-btc-tx.md diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/cookbook/parse-a-btc-tx.md b/i18n/fr/docusaurus-plugin-content-docs/current/cookbook/parse-a-btc-tx.md new file mode 100644 index 0000000000..f42dcee690 --- /dev/null +++ b/i18n/fr/docusaurus-plugin-content-docs/current/cookbook/parse-a-btc-tx.md @@ -0,0 +1,53 @@ +--- +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. From 81cb60ed553f55fadd680bd59eacf14560ea4474 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Tue, 4 Jul 2023 23:56:59 +0200 Subject: [PATCH 1147/1444] New translations parse-a-btc-tx.md (Spanish) --- .../current/cookbook/parse-a-btc-tx.md | 53 +++++++++++++++++++ 1 file changed, 53 insertions(+) create mode 100644 i18n/es/docusaurus-plugin-content-docs/current/cookbook/parse-a-btc-tx.md diff --git a/i18n/es/docusaurus-plugin-content-docs/current/cookbook/parse-a-btc-tx.md b/i18n/es/docusaurus-plugin-content-docs/current/cookbook/parse-a-btc-tx.md new file mode 100644 index 0000000000..f42dcee690 --- /dev/null +++ b/i18n/es/docusaurus-plugin-content-docs/current/cookbook/parse-a-btc-tx.md @@ -0,0 +1,53 @@ +--- +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. From 8da6fdb41e0bf617bf109a24fad07608109244e9 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Tue, 4 Jul 2023 23:57:00 +0200 Subject: [PATCH 1148/1444] New translations parse-a-btc-tx.md (German) --- .../current/cookbook/parse-a-btc-tx.md | 53 +++++++++++++++++++ 1 file changed, 53 insertions(+) create mode 100644 i18n/de/docusaurus-plugin-content-docs/current/cookbook/parse-a-btc-tx.md diff --git a/i18n/de/docusaurus-plugin-content-docs/current/cookbook/parse-a-btc-tx.md b/i18n/de/docusaurus-plugin-content-docs/current/cookbook/parse-a-btc-tx.md new file mode 100644 index 0000000000..f42dcee690 --- /dev/null +++ b/i18n/de/docusaurus-plugin-content-docs/current/cookbook/parse-a-btc-tx.md @@ -0,0 +1,53 @@ +--- +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. From 18017c09aca2b8acf18e3561816d6e2d791032e2 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Tue, 4 Jul 2023 23:57:00 +0200 Subject: [PATCH 1149/1444] New translations parse-a-btc-tx.md (Japanese) --- .../current/cookbook/parse-a-btc-tx.md | 53 +++++++++++++++++++ 1 file changed, 53 insertions(+) create mode 100644 i18n/ja/docusaurus-plugin-content-docs/current/cookbook/parse-a-btc-tx.md diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/cookbook/parse-a-btc-tx.md b/i18n/ja/docusaurus-plugin-content-docs/current/cookbook/parse-a-btc-tx.md new file mode 100644 index 0000000000..f42dcee690 --- /dev/null +++ b/i18n/ja/docusaurus-plugin-content-docs/current/cookbook/parse-a-btc-tx.md @@ -0,0 +1,53 @@ +--- +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. From 4585b0191b370417fa239631b9c773b2b2a5b3cc Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Tue, 4 Jul 2023 23:57:01 +0200 Subject: [PATCH 1150/1444] New translations parse-a-btc-tx.md (Korean) --- .../current/cookbook/parse-a-btc-tx.md | 53 +++++++++++++++++++ 1 file changed, 53 insertions(+) create mode 100644 i18n/ko/docusaurus-plugin-content-docs/current/cookbook/parse-a-btc-tx.md diff --git a/i18n/ko/docusaurus-plugin-content-docs/current/cookbook/parse-a-btc-tx.md b/i18n/ko/docusaurus-plugin-content-docs/current/cookbook/parse-a-btc-tx.md new file mode 100644 index 0000000000..f42dcee690 --- /dev/null +++ b/i18n/ko/docusaurus-plugin-content-docs/current/cookbook/parse-a-btc-tx.md @@ -0,0 +1,53 @@ +--- +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. From a44934266d01106f82bdc0067e12ecbc764c74f0 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Tue, 4 Jul 2023 23:57:02 +0200 Subject: [PATCH 1151/1444] New translations parse-a-btc-tx.md (Russian) --- .../current/cookbook/parse-a-btc-tx.md | 53 +++++++++++++++++++ 1 file changed, 53 insertions(+) create mode 100644 i18n/ru/docusaurus-plugin-content-docs/current/cookbook/parse-a-btc-tx.md diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/cookbook/parse-a-btc-tx.md b/i18n/ru/docusaurus-plugin-content-docs/current/cookbook/parse-a-btc-tx.md new file mode 100644 index 0000000000..f42dcee690 --- /dev/null +++ b/i18n/ru/docusaurus-plugin-content-docs/current/cookbook/parse-a-btc-tx.md @@ -0,0 +1,53 @@ +--- +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. From 27b99dc94a3275320dba69cd358f845a107649eb Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Tue, 4 Jul 2023 23:57:03 +0200 Subject: [PATCH 1152/1444] New translations parse-a-btc-tx.md (Turkish) --- .../current/cookbook/parse-a-btc-tx.md | 53 +++++++++++++++++++ 1 file changed, 53 insertions(+) create mode 100644 i18n/tr/docusaurus-plugin-content-docs/current/cookbook/parse-a-btc-tx.md diff --git a/i18n/tr/docusaurus-plugin-content-docs/current/cookbook/parse-a-btc-tx.md b/i18n/tr/docusaurus-plugin-content-docs/current/cookbook/parse-a-btc-tx.md new file mode 100644 index 0000000000..f42dcee690 --- /dev/null +++ b/i18n/tr/docusaurus-plugin-content-docs/current/cookbook/parse-a-btc-tx.md @@ -0,0 +1,53 @@ +--- +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. From c4eed056235552dcd4d28e0ef6ca85b08661c5ee Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Tue, 4 Jul 2023 23:57:04 +0200 Subject: [PATCH 1153/1444] New translations parse-a-btc-tx.md (Chinese Simplified) --- .../current/cookbook/parse-a-btc-tx.md | 53 +++++++++++++++++++ 1 file changed, 53 insertions(+) create mode 100644 i18n/zh/docusaurus-plugin-content-docs/current/cookbook/parse-a-btc-tx.md diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/cookbook/parse-a-btc-tx.md b/i18n/zh/docusaurus-plugin-content-docs/current/cookbook/parse-a-btc-tx.md new file mode 100644 index 0000000000..f42dcee690 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/current/cookbook/parse-a-btc-tx.md @@ -0,0 +1,53 @@ +--- +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. From 9a2715d927bd74f9e9626d359b07b0c0b331e749 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Tue, 4 Jul 2023 23:57:05 +0200 Subject: [PATCH 1154/1444] New translations parse-a-btc-tx.md (Vietnamese) --- .../current/cookbook/parse-a-btc-tx.md | 53 +++++++++++++++++++ 1 file changed, 53 insertions(+) create mode 100644 i18n/vi/docusaurus-plugin-content-docs/current/cookbook/parse-a-btc-tx.md diff --git a/i18n/vi/docusaurus-plugin-content-docs/current/cookbook/parse-a-btc-tx.md b/i18n/vi/docusaurus-plugin-content-docs/current/cookbook/parse-a-btc-tx.md new file mode 100644 index 0000000000..f42dcee690 --- /dev/null +++ b/i18n/vi/docusaurus-plugin-content-docs/current/cookbook/parse-a-btc-tx.md @@ -0,0 +1,53 @@ +--- +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. From 12b8fca11df1c9bc700d6e8db283f81aa619de80 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Tue, 4 Jul 2023 23:57:06 +0200 Subject: [PATCH 1155/1444] New translations parse-a-btc-tx.md (Portuguese, Brazilian) --- .../current/cookbook/parse-a-btc-tx.md | 53 +++++++++++++++++++ 1 file changed, 53 insertions(+) create mode 100644 i18n/pt/docusaurus-plugin-content-docs/current/cookbook/parse-a-btc-tx.md diff --git a/i18n/pt/docusaurus-plugin-content-docs/current/cookbook/parse-a-btc-tx.md b/i18n/pt/docusaurus-plugin-content-docs/current/cookbook/parse-a-btc-tx.md new file mode 100644 index 0000000000..f42dcee690 --- /dev/null +++ b/i18n/pt/docusaurus-plugin-content-docs/current/cookbook/parse-a-btc-tx.md @@ -0,0 +1,53 @@ +--- +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. From ae32cb34943d3c7b8cac4bf9314ec0afa744f27b Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Tue, 4 Jul 2023 23:57:06 +0200 Subject: [PATCH 1156/1444] New translations parse-a-btc-tx.md (Indonesian) --- .../current/cookbook/parse-a-btc-tx.md | 53 +++++++++++++++++++ 1 file changed, 53 insertions(+) create mode 100644 i18n/id/docusaurus-plugin-content-docs/current/cookbook/parse-a-btc-tx.md diff --git a/i18n/id/docusaurus-plugin-content-docs/current/cookbook/parse-a-btc-tx.md b/i18n/id/docusaurus-plugin-content-docs/current/cookbook/parse-a-btc-tx.md new file mode 100644 index 0000000000..f42dcee690 --- /dev/null +++ b/i18n/id/docusaurus-plugin-content-docs/current/cookbook/parse-a-btc-tx.md @@ -0,0 +1,53 @@ +--- +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. From ea3f49cb61f5c4ea33b6c05ad4026e26fd517d7a Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Tue, 4 Jul 2023 23:57:07 +0200 Subject: [PATCH 1157/1444] New translations parse-a-btc-tx.md (Hindi) --- .../current/cookbook/parse-a-btc-tx.md | 53 +++++++++++++++++++ 1 file changed, 53 insertions(+) create mode 100644 i18n/hi/docusaurus-plugin-content-docs/current/cookbook/parse-a-btc-tx.md diff --git a/i18n/hi/docusaurus-plugin-content-docs/current/cookbook/parse-a-btc-tx.md b/i18n/hi/docusaurus-plugin-content-docs/current/cookbook/parse-a-btc-tx.md new file mode 100644 index 0000000000..f42dcee690 --- /dev/null +++ b/i18n/hi/docusaurus-plugin-content-docs/current/cookbook/parse-a-btc-tx.md @@ -0,0 +1,53 @@ +--- +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. From 44518b68a13573423ff87651ae4498ca86cb16ec Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Wed, 5 Jul 2023 12:30:38 +0200 Subject: [PATCH 1158/1444] Update source file index.md --- docs/cookbook/index.md | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/docs/cookbook/index.md b/docs/cookbook/index.md index 6b0eb96f59..9a40e62b46 100644 --- a/docs/cookbook/index.md +++ b/docs/cookbook/index.md @@ -19,6 +19,10 @@ 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 @@ -43,10 +47,6 @@ Simple mining pool Proof of PoX payout -## Oracles - -Creating a simple BTC price oracle - ## Frontend [Post conditions with Stacks.js](./post-conditions) @@ -55,6 +55,8 @@ Creating a simple BTC price oracle [Sending transactions with Stacks.js](./stacks-js-sending-transactions) +Authenticating with Sign in with Stacks + ## Complete Apps [Sup](https://github.com/kenrogers/sup) From a83d8b3b0a4d7b55a85bf49eae84b6e6e99e3a50 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Wed, 5 Jul 2023 12:30:38 +0200 Subject: [PATCH 1159/1444] Update source file parse-a-btc-tx.md --- docs/cookbook/parse-a-btc-tx.md | 53 +++++++++++++++++++++++++++++++++ 1 file changed, 53 insertions(+) create mode 100644 docs/cookbook/parse-a-btc-tx.md diff --git a/docs/cookbook/parse-a-btc-tx.md b/docs/cookbook/parse-a-btc-tx.md new file mode 100644 index 0000000000..f42dcee690 --- /dev/null +++ b/docs/cookbook/parse-a-btc-tx.md @@ -0,0 +1,53 @@ +--- +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. From 84240ffcaf6d47b7059aa65496186f93dccae749 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Wed, 5 Jul 2023 12:30:56 +0200 Subject: [PATCH 1160/1444] New translations index.md (French) --- .../fr/docusaurus-plugin-content-docs/current/cookbook/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/cookbook/index.md b/i18n/fr/docusaurus-plugin-content-docs/current/cookbook/index.md index 9a40e62b46..086aadd794 100644 --- a/i18n/fr/docusaurus-plugin-content-docs/current/cookbook/index.md +++ b/i18n/fr/docusaurus-plugin-content-docs/current/cookbook/index.md @@ -13,7 +13,7 @@ Got an idea you think would make a good addition? We're always [accepting contri ## Bitcoin Integration -[Sending Bitcoin with Hiro wallet](./sending-bitcoin-with-hiro-wallet.md) +[Envoi de Bitcoin avec le portefeuille Hiro](./sending-bitcoin-with-hiro-wallet.md) Getting a Stacks address from a public key From da41f26364e3f64df6028d8027ec5eca9a01c220 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Wed, 5 Jul 2023 12:30:57 +0200 Subject: [PATCH 1161/1444] New translations sending-bitcoin-with-hiro-wallet.md (French) --- .../sending-bitcoin-with-hiro-wallet.md | 32 +++++++++---------- 1 file changed, 16 insertions(+), 16 deletions(-) diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/cookbook/sending-bitcoin-with-hiro-wallet.md b/i18n/fr/docusaurus-plugin-content-docs/current/cookbook/sending-bitcoin-with-hiro-wallet.md index fda05f7356..260dd4184b 100644 --- a/i18n/fr/docusaurus-plugin-content-docs/current/cookbook/sending-bitcoin-with-hiro-wallet.md +++ b/i18n/fr/docusaurus-plugin-content-docs/current/cookbook/sending-bitcoin-with-hiro-wallet.md @@ -1,38 +1,38 @@ --- -title: Sending Bitcoin with Hiro Wallet -description: Initiate a basic Bitcoin transaction with the Hiro wallet +title: Envoi de Bitcoin avec le portefeuille Hiro +description: Lancer une transaction standard Bitcoin avec le portefeuille Hiro --- -Using Hiro's web wallet, we can easily initiate a simple Bitcoin transaction using only a few lines of code. +En utilisant le portefeuille web d'Hiro, nous pouvons facilement initier une transaction Bitcoin simple avec seulement quelques lignes de 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. +Vous devrez être authentifié avec le portefeuille Hiro pour que cela fonctionne, consultez comment faire dans le guide [Authentification avec Stacks.js](./stacks-js-auth). -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. +Une fois que vous avez connecté le portefeuille, vous pouvez utiliser l'API Hiro Wallet pour initier une simple transaction Bitcoin dans votre application JS de cette façon. ```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 + const resp = attendre window.btc?. equest("sendTransfer", { + adresse: "tb1qya9wtp4dyq67ldxz2pyuz40esvgd0cgx9s3pjl", //remplacez ceci par n'importe quelle adresse que vous voulez envoyer au montant de + : "10000", // le montant que vous voulez envoyer en 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)); + // Stockage de txid dans le stockage local + // Nous récupérerons la transaction IF, que nous pouvons ensuite utiliser pour faire ce que nous voulons + si (typeof window ! = "undefined") { + localStorage. etItem("txid", JSON.stringify(resp.resultat. xid)); } - // 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 + // Nous pouvons vouloir faire quelque chose une fois cette transaction confirmée, pour que nous puissions le mettre en attente ici et ensuite utiliser une API comme mempool. le rythme de requête de la chaîne Bitcoin pour obtenir des informations sur cette transaction localStorage.setItem("txStatus", "pending"); }; ``` -Then all we would do is hook up our button to call this `sendBitcoin` function. +Ensuite, tout ce que nous ferions est de brancher notre bouton pour appeler cette fonction `sendBitcoins`. ```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. +Vous pouvez jeter un coup d'œil au guide [Vérifier une transaction sur la chaîne BTC](./verifying-a-btc-tx-was-mined.md) pour voir un flux utilisateur plus complexe de vérification d'une transaction qui a été miné en utilisant cet ID retourné comme point de départ. -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). +Vous pouvez jeter un coup d'oeil à un peu plus d'informations sur cette simple API sur la [documentation du développeur de portefeuille Hiro](https://hirowallet.gitbook.io/developers/bitcoin/sign-transactions/sending-bitcoin). From 932cc46f54cb688a1288fa96c7ccfc61e55ecdd8 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Tue, 18 Jul 2023 22:24:35 +0200 Subject: [PATCH 1162/1444] New translations creating-an-nft.md (French) --- .../current/cookbook/creating-an-nft.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/cookbook/creating-an-nft.md b/i18n/fr/docusaurus-plugin-content-docs/current/cookbook/creating-an-nft.md index 08faf9393a..851189579e 100644 --- a/i18n/fr/docusaurus-plugin-content-docs/current/cookbook/creating-an-nft.md +++ b/i18n/fr/docusaurus-plugin-content-docs/current/cookbook/creating-an-nft.md @@ -8,7 +8,7 @@ Clarity makes creating NFTs incredibly easy. With built-in functions for creatin Let's see how. :::tip -Code for this recipe has been pulled from [this NFT tutorial](https://blog.developerdao.com/building-an-nft-with-stacks-and-clarity) from Developer DAO. +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 From 68e433cf993790f8c5e5753d2919bd6fbf5c0e88 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Tue, 18 Jul 2023 22:24:36 +0200 Subject: [PATCH 1163/1444] New translations creating-an-nft.md (Spanish) --- .../current/cookbook/creating-an-nft.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/i18n/es/docusaurus-plugin-content-docs/current/cookbook/creating-an-nft.md b/i18n/es/docusaurus-plugin-content-docs/current/cookbook/creating-an-nft.md index 08faf9393a..851189579e 100644 --- a/i18n/es/docusaurus-plugin-content-docs/current/cookbook/creating-an-nft.md +++ b/i18n/es/docusaurus-plugin-content-docs/current/cookbook/creating-an-nft.md @@ -8,7 +8,7 @@ Clarity makes creating NFTs incredibly easy. With built-in functions for creatin Let's see how. :::tip -Code for this recipe has been pulled from [this NFT tutorial](https://blog.developerdao.com/building-an-nft-with-stacks-and-clarity) from Developer DAO. +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 From 05b1eedb582241085e54d9c725ab3dc2aa1836e4 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Tue, 18 Jul 2023 22:24:37 +0200 Subject: [PATCH 1164/1444] New translations creating-an-nft.md (German) --- .../current/cookbook/creating-an-nft.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/i18n/de/docusaurus-plugin-content-docs/current/cookbook/creating-an-nft.md b/i18n/de/docusaurus-plugin-content-docs/current/cookbook/creating-an-nft.md index 08faf9393a..851189579e 100644 --- a/i18n/de/docusaurus-plugin-content-docs/current/cookbook/creating-an-nft.md +++ b/i18n/de/docusaurus-plugin-content-docs/current/cookbook/creating-an-nft.md @@ -8,7 +8,7 @@ Clarity makes creating NFTs incredibly easy. With built-in functions for creatin Let's see how. :::tip -Code for this recipe has been pulled from [this NFT tutorial](https://blog.developerdao.com/building-an-nft-with-stacks-and-clarity) from Developer DAO. +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 From 8a44566d65a8c4d5f042ce06470f8986610b719b Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Tue, 18 Jul 2023 22:24:38 +0200 Subject: [PATCH 1165/1444] New translations creating-an-nft.md (Japanese) --- .../current/cookbook/creating-an-nft.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/cookbook/creating-an-nft.md b/i18n/ja/docusaurus-plugin-content-docs/current/cookbook/creating-an-nft.md index 08faf9393a..851189579e 100644 --- a/i18n/ja/docusaurus-plugin-content-docs/current/cookbook/creating-an-nft.md +++ b/i18n/ja/docusaurus-plugin-content-docs/current/cookbook/creating-an-nft.md @@ -8,7 +8,7 @@ Clarity makes creating NFTs incredibly easy. With built-in functions for creatin Let's see how. :::tip -Code for this recipe has been pulled from [this NFT tutorial](https://blog.developerdao.com/building-an-nft-with-stacks-and-clarity) from Developer DAO. +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 From fd576176a673bc67a29de7602f8cbd27e0e9f399 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Tue, 18 Jul 2023 22:24:39 +0200 Subject: [PATCH 1166/1444] New translations creating-an-nft.md (Korean) --- .../current/cookbook/creating-an-nft.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/i18n/ko/docusaurus-plugin-content-docs/current/cookbook/creating-an-nft.md b/i18n/ko/docusaurus-plugin-content-docs/current/cookbook/creating-an-nft.md index 08faf9393a..851189579e 100644 --- a/i18n/ko/docusaurus-plugin-content-docs/current/cookbook/creating-an-nft.md +++ b/i18n/ko/docusaurus-plugin-content-docs/current/cookbook/creating-an-nft.md @@ -8,7 +8,7 @@ Clarity makes creating NFTs incredibly easy. With built-in functions for creatin Let's see how. :::tip -Code for this recipe has been pulled from [this NFT tutorial](https://blog.developerdao.com/building-an-nft-with-stacks-and-clarity) from Developer DAO. +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 From ce2fb4a27b3776a3c78eeb568895338012b35c3d Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Tue, 18 Jul 2023 22:24:40 +0200 Subject: [PATCH 1167/1444] New translations creating-an-nft.md (Russian) --- .../current/cookbook/creating-an-nft.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/cookbook/creating-an-nft.md b/i18n/ru/docusaurus-plugin-content-docs/current/cookbook/creating-an-nft.md index 08faf9393a..851189579e 100644 --- a/i18n/ru/docusaurus-plugin-content-docs/current/cookbook/creating-an-nft.md +++ b/i18n/ru/docusaurus-plugin-content-docs/current/cookbook/creating-an-nft.md @@ -8,7 +8,7 @@ Clarity makes creating NFTs incredibly easy. With built-in functions for creatin Let's see how. :::tip -Code for this recipe has been pulled from [this NFT tutorial](https://blog.developerdao.com/building-an-nft-with-stacks-and-clarity) from Developer DAO. +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 From 8d8b587b1d69b873784fe916d50619475b284ff6 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Tue, 18 Jul 2023 22:24:41 +0200 Subject: [PATCH 1168/1444] New translations creating-an-nft.md (Turkish) --- .../current/cookbook/creating-an-nft.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/i18n/tr/docusaurus-plugin-content-docs/current/cookbook/creating-an-nft.md b/i18n/tr/docusaurus-plugin-content-docs/current/cookbook/creating-an-nft.md index 08faf9393a..851189579e 100644 --- a/i18n/tr/docusaurus-plugin-content-docs/current/cookbook/creating-an-nft.md +++ b/i18n/tr/docusaurus-plugin-content-docs/current/cookbook/creating-an-nft.md @@ -8,7 +8,7 @@ Clarity makes creating NFTs incredibly easy. With built-in functions for creatin Let's see how. :::tip -Code for this recipe has been pulled from [this NFT tutorial](https://blog.developerdao.com/building-an-nft-with-stacks-and-clarity) from Developer DAO. +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 From f52d2a361638da1c8dbc438cc60e570da708319e Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Tue, 18 Jul 2023 22:24:41 +0200 Subject: [PATCH 1169/1444] New translations creating-an-nft.md (Chinese Simplified) --- .../current/cookbook/creating-an-nft.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/cookbook/creating-an-nft.md b/i18n/zh/docusaurus-plugin-content-docs/current/cookbook/creating-an-nft.md index 08faf9393a..851189579e 100644 --- a/i18n/zh/docusaurus-plugin-content-docs/current/cookbook/creating-an-nft.md +++ b/i18n/zh/docusaurus-plugin-content-docs/current/cookbook/creating-an-nft.md @@ -8,7 +8,7 @@ Clarity makes creating NFTs incredibly easy. With built-in functions for creatin Let's see how. :::tip -Code for this recipe has been pulled from [this NFT tutorial](https://blog.developerdao.com/building-an-nft-with-stacks-and-clarity) from Developer DAO. +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 From 796eb329217638bfef9169a60cab5d16d7072610 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Tue, 18 Jul 2023 22:24:42 +0200 Subject: [PATCH 1170/1444] New translations creating-an-nft.md (Vietnamese) --- .../current/cookbook/creating-an-nft.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/i18n/vi/docusaurus-plugin-content-docs/current/cookbook/creating-an-nft.md b/i18n/vi/docusaurus-plugin-content-docs/current/cookbook/creating-an-nft.md index 08faf9393a..851189579e 100644 --- a/i18n/vi/docusaurus-plugin-content-docs/current/cookbook/creating-an-nft.md +++ b/i18n/vi/docusaurus-plugin-content-docs/current/cookbook/creating-an-nft.md @@ -8,7 +8,7 @@ Clarity makes creating NFTs incredibly easy. With built-in functions for creatin Let's see how. :::tip -Code for this recipe has been pulled from [this NFT tutorial](https://blog.developerdao.com/building-an-nft-with-stacks-and-clarity) from Developer DAO. +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 From be668d90e5b15ab7d0983ceff39eb03e06cb428d Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Tue, 18 Jul 2023 22:24:43 +0200 Subject: [PATCH 1171/1444] New translations creating-an-nft.md (Portuguese, Brazilian) --- .../current/cookbook/creating-an-nft.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/i18n/pt/docusaurus-plugin-content-docs/current/cookbook/creating-an-nft.md b/i18n/pt/docusaurus-plugin-content-docs/current/cookbook/creating-an-nft.md index 08faf9393a..851189579e 100644 --- a/i18n/pt/docusaurus-plugin-content-docs/current/cookbook/creating-an-nft.md +++ b/i18n/pt/docusaurus-plugin-content-docs/current/cookbook/creating-an-nft.md @@ -8,7 +8,7 @@ Clarity makes creating NFTs incredibly easy. With built-in functions for creatin Let's see how. :::tip -Code for this recipe has been pulled from [this NFT tutorial](https://blog.developerdao.com/building-an-nft-with-stacks-and-clarity) from Developer DAO. +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 From f24bac3f18691d20dd641be9107a2bdc4b04f691 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Tue, 18 Jul 2023 22:24:44 +0200 Subject: [PATCH 1172/1444] New translations creating-an-nft.md (Indonesian) --- .../current/cookbook/creating-an-nft.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/i18n/id/docusaurus-plugin-content-docs/current/cookbook/creating-an-nft.md b/i18n/id/docusaurus-plugin-content-docs/current/cookbook/creating-an-nft.md index 08faf9393a..851189579e 100644 --- a/i18n/id/docusaurus-plugin-content-docs/current/cookbook/creating-an-nft.md +++ b/i18n/id/docusaurus-plugin-content-docs/current/cookbook/creating-an-nft.md @@ -8,7 +8,7 @@ Clarity makes creating NFTs incredibly easy. With built-in functions for creatin Let's see how. :::tip -Code for this recipe has been pulled from [this NFT tutorial](https://blog.developerdao.com/building-an-nft-with-stacks-and-clarity) from Developer DAO. +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 From 13d4ea840edac059a2f4e2c3813b439ae293db11 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Tue, 18 Jul 2023 22:24:45 +0200 Subject: [PATCH 1173/1444] New translations creating-an-nft.md (Hindi) --- .../current/cookbook/creating-an-nft.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/i18n/hi/docusaurus-plugin-content-docs/current/cookbook/creating-an-nft.md b/i18n/hi/docusaurus-plugin-content-docs/current/cookbook/creating-an-nft.md index 08faf9393a..851189579e 100644 --- a/i18n/hi/docusaurus-plugin-content-docs/current/cookbook/creating-an-nft.md +++ b/i18n/hi/docusaurus-plugin-content-docs/current/cookbook/creating-an-nft.md @@ -8,7 +8,7 @@ Clarity makes creating NFTs incredibly easy. With built-in functions for creatin Let's see how. :::tip -Code for this recipe has been pulled from [this NFT tutorial](https://blog.developerdao.com/building-an-nft-with-stacks-and-clarity) from Developer DAO. +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 From eab2aff3da2ffa7b365819042c91e3498a7c3c99 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Tue, 18 Jul 2023 23:23:35 +0200 Subject: [PATCH 1174/1444] Update source file creating-an-nft.md --- docs/cookbook/creating-an-nft.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/cookbook/creating-an-nft.md b/docs/cookbook/creating-an-nft.md index 08faf9393a..851189579e 100644 --- a/docs/cookbook/creating-an-nft.md +++ b/docs/cookbook/creating-an-nft.md @@ -8,7 +8,7 @@ Clarity makes creating NFTs incredibly easy. With built-in functions for creatin Let's see how. :::tip -Code for this recipe has been pulled from [this NFT tutorial](https://blog.developerdao.com/building-an-nft-with-stacks-and-clarity) from Developer DAO. +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 From 22bc90b5fa6fd220f6eca69d08ba9adba67dea43 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Fri, 4 Aug 2023 06:49:37 +0200 Subject: [PATCH 1175/1444] New translations _category_.json (Indonesian) --- .../current/clarity/noteworthy-contracts/_category_.json | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/i18n/id/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/_category_.json b/i18n/id/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/_category_.json index eb32d48e32..6b4389e015 100644 --- a/i18n/id/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/_category_.json +++ b/i18n/id/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/_category_.json @@ -1,8 +1,8 @@ { - "label": "Noteworthy Contracts", + "label": "Kontrak Penting", "position": 5, "link": { "type": "generated-index", - "description": "Specific deployed Clarity Contracts worth mentioning." + "description": "Kontrak Clarity yang telah diimplementasikan secara khusus yang pantas disebutkan." } } From 5d0b6756d2bb98c674e7f28e23a973579919ebae Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Fri, 4 Aug 2023 06:49:38 +0200 Subject: [PATCH 1176/1444] New translations bns-contract.md (Indonesian) --- .../noteworthy-contracts/bns-contract.md | 22 +++++++++---------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/i18n/id/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/bns-contract.md b/i18n/id/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/bns-contract.md index 3e03181cd8..535d0cc942 100644 --- a/i18n/id/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/bns-contract.md +++ b/i18n/id/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/bns-contract.md @@ -1,23 +1,23 @@ --- -title: BNS Contract -description: The Bitcoin Name System. +title: Kontrak BNS +description: Sebuah Sistem Penamaan Bitcoin. --- ![](/img/satoshi-btc.png) ## Pengantar -The Bitcoin Name System (BNS) is implemented as a smart contract using Clarity. +BNS (Bitcoin Name System) dijalankan sebagai kontrak pintar menggunakan Clarity. -Below is a list of public and read-only functions as well as error codes that can be returned by those methods: +Berikut adalah daftar fungsi publik dan hanya baca (read-only), serta kode kesalahan yang dapat dikembalikan oleh metode-metode tersebut: -- [Public functions](#public-functions) -- [Read-only functions](#read-only-functions) -- [Error codes](#error-codes) +- [Fungsi yang dapat diakses publik](#public-functions) +- [Fungsi dengan akses baca saja](#read-only-functions) +- [Kode galat](#error-codes) -## Public functions +## Fungsi yang dapat diakses publik -### name-import +### nama-impor #### Input: `(buff 20), (buff 48), principal, (buff 20)` @@ -166,7 +166,7 @@ Example: - buckets 7, 8, 9, 10, 11, 12, 13, 14: 7 - buckets 15, 16+: -## Read-only functions +## Fungsi dengan akses baca saja ### can-name-be-registered @@ -276,7 +276,7 @@ Get name registration details. Returns the registered name that a principal owns if there is one. A principal can only own one name at a time. -## Error codes +## Kode galat ### ERR_INSUFFICIENT_FUNDS From db81a74b1be0754127182acb0fdc76891e80b442 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Fri, 4 Aug 2023 06:49:39 +0200 Subject: [PATCH 1177/1444] New translations stacking-contract.md (Indonesian) --- .../noteworthy-contracts/stacking-contract.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/i18n/id/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/stacking-contract.md b/i18n/id/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/stacking-contract.md index 749679a4fa..43abda2683 100644 --- a/i18n/id/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/stacking-contract.md +++ b/i18n/id/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/stacking-contract.md @@ -8,13 +8,13 @@ sidebar_position: 6 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: +Berikut adalah daftar fungsi publik dan hanya baca (read-only), serta kode kesalahan yang dapat dikembalikan oleh metode-metode tersebut: -- [Public functions](#public-functions) -- [Read-only functions](#read-only-functions) -- [Error codes](#error-codes) +- [Fungsi yang dapat diakses publik](#public-functions) +- [Fungsi dengan akses baca saja](#read-only-functions) +- [Kode galat](#error-codes) -## Public functions +## Fungsi yang dapat diakses publik ### allow-contract-caller @@ -149,7 +149,7 @@ This is the self-service interface. tx-sender will be the Stacker. The tokens will unlock and be returned to the Stacker (tx-sender) automatically. -## Read-only functions +## Fungsi dengan akses baca saja ### can-stack-stx @@ -235,7 +235,7 @@ Returns the amount of currently participating uSTX in the given cycle. Returns whether or not PoX has been rejected at a given PoX cycle. -## Error codes +## Kode galat ### ERR_DELEGATION_EXPIRES_DURING_LOCK From d6b6a8dfc0f74d11ac761368c0edb794a4e5a173 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Fri, 4 Aug 2023 07:55:59 +0200 Subject: [PATCH 1178/1444] New translations bns-contract.md (Indonesian) --- .../current/clarity/noteworthy-contracts/bns-contract.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/i18n/id/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/bns-contract.md b/i18n/id/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/bns-contract.md index 535d0cc942..c54d8727e4 100644 --- a/i18n/id/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/bns-contract.md +++ b/i18n/id/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/bns-contract.md @@ -27,7 +27,7 @@ Berikut adalah daftar fungsi publik dan hanya baca (read-only), serta kode kesal #### Description: -Imports name to a revealed namespace. Each imported name is given both an owner and some off-chain state. +Menyertakan nama ke dalam ruang nama yang terbuka. Setiap nama yang diimpor diberikan pemilik dan beberapa keadaan di luar rantai blok. ### name-preorder @@ -39,7 +39,7 @@ Imports name to a revealed namespace. Each imported name is given both an owner #### 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. +Memesan nama dengan memberitahukan seluruh node BNS hash yang diacak dari nama BNS. Biaya pendaftaran dibayarkan ke alamat yang telah ditetapkan oleh pemilik ruang nama. ### name-register @@ -51,7 +51,7 @@ Preorders a name by telling all BNS nodes the salted hash of the BNS name. It pa #### Description: -Reveals the salt and the name to all BNS nodes, and assigns the name an initial public key hash and zone file hash. +Mengungkapkan salt dan nama ke semua node BNS, dan menetapkan hash kunci publik awal dan hash file zona untuk nama tersebut. ### name-renewal From 771577480ddd79cd7463b7e5deb1f09cedc5ab29 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Wed, 23 Aug 2023 17:27:13 +0200 Subject: [PATCH 1179/1444] New translations index.md (French) --- i18n/fr/docusaurus-plugin-content-docs/current/clarity/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/clarity/index.md b/i18n/fr/docusaurus-plugin-content-docs/current/clarity/index.md index fd941bc266..a90f91b599 100644 --- a/i18n/fr/docusaurus-plugin-content-docs/current/clarity/index.md +++ b/i18n/fr/docusaurus-plugin-content-docs/current/clarity/index.md @@ -23,7 +23,7 @@ One of the core precepts of Clarity is that it is secure by design. The design p ### 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?2 With Clarity, what you see is what you get. +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 From a1acb250e6e2d82faa5bdbcdb770d683f0c1264b Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Wed, 23 Aug 2023 17:27:14 +0200 Subject: [PATCH 1180/1444] New translations index.md (Spanish) --- i18n/es/docusaurus-plugin-content-docs/current/clarity/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/i18n/es/docusaurus-plugin-content-docs/current/clarity/index.md b/i18n/es/docusaurus-plugin-content-docs/current/clarity/index.md index 34bcc6aa3d..859fb5a1fa 100644 --- a/i18n/es/docusaurus-plugin-content-docs/current/clarity/index.md +++ b/i18n/es/docusaurus-plugin-content-docs/current/clarity/index.md @@ -23,7 +23,7 @@ One of the core precepts of Clarity is that it is secure by design. The design p ### 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?2 With Clarity, what you see is what you get. +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 From 3f1851486b71dfcc1d24adc9d5e5a7de055d45d4 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Wed, 23 Aug 2023 17:27:15 +0200 Subject: [PATCH 1181/1444] New translations index.md (German) --- i18n/de/docusaurus-plugin-content-docs/current/clarity/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/i18n/de/docusaurus-plugin-content-docs/current/clarity/index.md b/i18n/de/docusaurus-plugin-content-docs/current/clarity/index.md index fd941bc266..a90f91b599 100644 --- a/i18n/de/docusaurus-plugin-content-docs/current/clarity/index.md +++ b/i18n/de/docusaurus-plugin-content-docs/current/clarity/index.md @@ -23,7 +23,7 @@ One of the core precepts of Clarity is that it is secure by design. The design p ### 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?2 With Clarity, what you see is what you get. +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 From 2ff865273b92ef3a3ba3475740c02e6cafb53c15 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Wed, 23 Aug 2023 17:27:16 +0200 Subject: [PATCH 1182/1444] New translations index.md (Japanese) --- i18n/ja/docusaurus-plugin-content-docs/current/clarity/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/clarity/index.md b/i18n/ja/docusaurus-plugin-content-docs/current/clarity/index.md index fd941bc266..a90f91b599 100644 --- a/i18n/ja/docusaurus-plugin-content-docs/current/clarity/index.md +++ b/i18n/ja/docusaurus-plugin-content-docs/current/clarity/index.md @@ -23,7 +23,7 @@ One of the core precepts of Clarity is that it is secure by design. The design p ### 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?2 With Clarity, what you see is what you get. +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 From 21e2417e2599d58ee13363766b31b57428f8dc89 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Wed, 23 Aug 2023 17:27:17 +0200 Subject: [PATCH 1183/1444] New translations index.md (Korean) --- i18n/ko/docusaurus-plugin-content-docs/current/clarity/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/i18n/ko/docusaurus-plugin-content-docs/current/clarity/index.md b/i18n/ko/docusaurus-plugin-content-docs/current/clarity/index.md index fd941bc266..a90f91b599 100644 --- a/i18n/ko/docusaurus-plugin-content-docs/current/clarity/index.md +++ b/i18n/ko/docusaurus-plugin-content-docs/current/clarity/index.md @@ -23,7 +23,7 @@ One of the core precepts of Clarity is that it is secure by design. The design p ### 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?2 With Clarity, what you see is what you get. +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 From 2e8076bfa09965b7eb3a703743abe776e8430a7a Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Wed, 23 Aug 2023 17:27:18 +0200 Subject: [PATCH 1184/1444] New translations index.md (Russian) --- i18n/ru/docusaurus-plugin-content-docs/current/clarity/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/clarity/index.md b/i18n/ru/docusaurus-plugin-content-docs/current/clarity/index.md index fd941bc266..a90f91b599 100644 --- a/i18n/ru/docusaurus-plugin-content-docs/current/clarity/index.md +++ b/i18n/ru/docusaurus-plugin-content-docs/current/clarity/index.md @@ -23,7 +23,7 @@ One of the core precepts of Clarity is that it is secure by design. The design p ### 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?2 With Clarity, what you see is what you get. +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 From a46cdcdb58f043a77e890b0cc62ab094059fe3e4 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Wed, 23 Aug 2023 17:27:19 +0200 Subject: [PATCH 1185/1444] New translations index.md (Turkish) --- i18n/tr/docusaurus-plugin-content-docs/current/clarity/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/i18n/tr/docusaurus-plugin-content-docs/current/clarity/index.md b/i18n/tr/docusaurus-plugin-content-docs/current/clarity/index.md index fd941bc266..a90f91b599 100644 --- a/i18n/tr/docusaurus-plugin-content-docs/current/clarity/index.md +++ b/i18n/tr/docusaurus-plugin-content-docs/current/clarity/index.md @@ -23,7 +23,7 @@ One of the core precepts of Clarity is that it is secure by design. The design p ### 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?2 With Clarity, what you see is what you get. +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 From d7762720df3bdb3e5886d1bedd054f6b7f5d1dc3 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Wed, 23 Aug 2023 17:27:20 +0200 Subject: [PATCH 1186/1444] New translations index.md (Chinese Simplified) --- i18n/zh/docusaurus-plugin-content-docs/current/clarity/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/clarity/index.md b/i18n/zh/docusaurus-plugin-content-docs/current/clarity/index.md index fd5bcd31c8..2426916d2c 100644 --- a/i18n/zh/docusaurus-plugin-content-docs/current/clarity/index.md +++ b/i18n/zh/docusaurus-plugin-content-docs/current/clarity/index.md @@ -23,7 +23,7 @@ One of the core precepts of Clarity is that it is secure by design. The design p ### 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?2 With Clarity, what you see is what you get. +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 From f87d71937563a633ace03d01de6e4b920bb59654 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Wed, 23 Aug 2023 17:27:21 +0200 Subject: [PATCH 1187/1444] New translations index.md (Vietnamese) --- i18n/vi/docusaurus-plugin-content-docs/current/clarity/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/i18n/vi/docusaurus-plugin-content-docs/current/clarity/index.md b/i18n/vi/docusaurus-plugin-content-docs/current/clarity/index.md index fd941bc266..a90f91b599 100644 --- a/i18n/vi/docusaurus-plugin-content-docs/current/clarity/index.md +++ b/i18n/vi/docusaurus-plugin-content-docs/current/clarity/index.md @@ -23,7 +23,7 @@ One of the core precepts of Clarity is that it is secure by design. The design p ### 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?2 With Clarity, what you see is what you get. +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 From aa6ae04358d5e81a53282ded379b3d87a1762cb2 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Wed, 23 Aug 2023 17:27:22 +0200 Subject: [PATCH 1188/1444] New translations index.md (Portuguese, Brazilian) --- i18n/pt/docusaurus-plugin-content-docs/current/clarity/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/i18n/pt/docusaurus-plugin-content-docs/current/clarity/index.md b/i18n/pt/docusaurus-plugin-content-docs/current/clarity/index.md index fd941bc266..a90f91b599 100644 --- a/i18n/pt/docusaurus-plugin-content-docs/current/clarity/index.md +++ b/i18n/pt/docusaurus-plugin-content-docs/current/clarity/index.md @@ -23,7 +23,7 @@ One of the core precepts of Clarity is that it is secure by design. The design p ### 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?2 With Clarity, what you see is what you get. +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 From 555daed6960e33c32cd1f552a51fb40f4fc94812 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Wed, 23 Aug 2023 17:27:23 +0200 Subject: [PATCH 1189/1444] New translations index.md (Indonesian) --- i18n/id/docusaurus-plugin-content-docs/current/clarity/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/i18n/id/docusaurus-plugin-content-docs/current/clarity/index.md b/i18n/id/docusaurus-plugin-content-docs/current/clarity/index.md index 0e32377f24..c664c233b0 100644 --- a/i18n/id/docusaurus-plugin-content-docs/current/clarity/index.md +++ b/i18n/id/docusaurus-plugin-content-docs/current/clarity/index.md @@ -23,7 +23,7 @@ One of the core precepts of Clarity is that it is secure by design. The design p ### 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?2 With Clarity, what you see is what you get. +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 From d191b37557bcfe30893b553879bb521cfe3fe289 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Wed, 23 Aug 2023 17:27:26 +0200 Subject: [PATCH 1190/1444] New translations index.md (Hindi) --- i18n/hi/docusaurus-plugin-content-docs/current/clarity/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/i18n/hi/docusaurus-plugin-content-docs/current/clarity/index.md b/i18n/hi/docusaurus-plugin-content-docs/current/clarity/index.md index fd941bc266..a90f91b599 100644 --- a/i18n/hi/docusaurus-plugin-content-docs/current/clarity/index.md +++ b/i18n/hi/docusaurus-plugin-content-docs/current/clarity/index.md @@ -23,7 +23,7 @@ One of the core precepts of Clarity is that it is secure by design. The design p ### 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?2 With Clarity, what you see is what you get. +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 From af03ab0dd44aebd14a3e11db723dbd7cd6264a6a Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Wed, 23 Aug 2023 18:34:10 +0200 Subject: [PATCH 1191/1444] Update source file index.md --- docs/clarity/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/clarity/index.md b/docs/clarity/index.md index fd941bc266..a90f91b599 100644 --- a/docs/clarity/index.md +++ b/docs/clarity/index.md @@ -23,7 +23,7 @@ One of the core precepts of Clarity is that it is secure by design. The design p ### 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?2 With Clarity, what you see is what you get. +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 From b7c6f20c1c6f13c73ba7236b04056c535a7f2645 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Mon, 18 Sep 2023 20:56:17 +0200 Subject: [PATCH 1192/1444] New translations bns.md (French) --- .../current/stacks-academy/bns.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/stacks-academy/bns.md b/i18n/fr/docusaurus-plugin-content-docs/current/stacks-academy/bns.md index a64344f3f0..cbe802715e 100644 --- a/i18n/fr/docusaurus-plugin-content-docs/current/stacks-academy/bns.md +++ b/i18n/fr/docusaurus-plugin-content-docs/current/stacks-academy/bns.md @@ -198,7 +198,7 @@ Parce que les noms de sous-domaine sont bon marché, les développeurs peuvent 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 +## BNS and DID Standards 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). @@ -231,7 +231,7 @@ Tous les noms n'auront pas forcément de DIDs qui seront résolus pour les clés Une API RESTful est en cours de développement. -## Encodage DID pour les sous-domaines +## DID Encoding for Subdomains 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. From 6d3443f5a22deba71cdd0990371f9a4d82e5615d Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Mon, 18 Sep 2023 20:56:18 +0200 Subject: [PATCH 1193/1444] New translations bns.md (Spanish) --- .../current/stacks-academy/bns.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/i18n/es/docusaurus-plugin-content-docs/current/stacks-academy/bns.md b/i18n/es/docusaurus-plugin-content-docs/current/stacks-academy/bns.md index 746fe290a3..a72b5ec6d0 100644 --- a/i18n/es/docusaurus-plugin-content-docs/current/stacks-academy/bns.md +++ b/i18n/es/docusaurus-plugin-content-docs/current/stacks-academy/bns.md @@ -201,7 +201,7 @@ Because subdomain names are cheap, developers may be inclined to run subdomain r 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 +## BNS and DID Standards 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). @@ -234,7 +234,7 @@ No todos los nombres tendrán DIDs que resuelvan claves públicas. Sin embargo, Una API RESTful está en desarrollo. -## Codificación DID para subdominios +## DID Encoding for Subdomains 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. From 744509ea73a9d6c030c9403f94f91644dadc4881 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Mon, 18 Sep 2023 20:56:19 +0200 Subject: [PATCH 1194/1444] New translations bns.md (German) --- .../current/stacks-academy/bns.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/i18n/de/docusaurus-plugin-content-docs/current/stacks-academy/bns.md b/i18n/de/docusaurus-plugin-content-docs/current/stacks-academy/bns.md index 8eb4f39376..6f7bb331ab 100644 --- a/i18n/de/docusaurus-plugin-content-docs/current/stacks-academy/bns.md +++ b/i18n/de/docusaurus-plugin-content-docs/current/stacks-academy/bns.md @@ -198,7 +198,7 @@ Because subdomain names are cheap, developers may be inclined to run subdomain r 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 and DID Standards BNS names are compliant with the emerging [Decentralized Identity Foundation](http://identity.foundation) protocol specification for decentralized identifiers (DIDs). From 8b39d97618db759e03cc91dbb4ac68891af2a560 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Mon, 18 Sep 2023 20:56:20 +0200 Subject: [PATCH 1195/1444] New translations bns.md (Japanese) --- .../current/stacks-academy/bns.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/stacks-academy/bns.md b/i18n/ja/docusaurus-plugin-content-docs/current/stacks-academy/bns.md index 8eb4f39376..6f7bb331ab 100644 --- a/i18n/ja/docusaurus-plugin-content-docs/current/stacks-academy/bns.md +++ b/i18n/ja/docusaurus-plugin-content-docs/current/stacks-academy/bns.md @@ -198,7 +198,7 @@ Because subdomain names are cheap, developers may be inclined to run subdomain r 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 and DID Standards BNS names are compliant with the emerging [Decentralized Identity Foundation](http://identity.foundation) protocol specification for decentralized identifiers (DIDs). From aead22cab6f38327d35f1ecc5627051457f7bbe9 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Mon, 18 Sep 2023 20:56:21 +0200 Subject: [PATCH 1196/1444] New translations bns.md (Korean) --- .../current/stacks-academy/bns.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/i18n/ko/docusaurus-plugin-content-docs/current/stacks-academy/bns.md b/i18n/ko/docusaurus-plugin-content-docs/current/stacks-academy/bns.md index 8eb4f39376..6f7bb331ab 100644 --- a/i18n/ko/docusaurus-plugin-content-docs/current/stacks-academy/bns.md +++ b/i18n/ko/docusaurus-plugin-content-docs/current/stacks-academy/bns.md @@ -198,7 +198,7 @@ Because subdomain names are cheap, developers may be inclined to run subdomain r 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 and DID Standards BNS names are compliant with the emerging [Decentralized Identity Foundation](http://identity.foundation) protocol specification for decentralized identifiers (DIDs). From 20bfc8fcd9b9b7113cfb16ed86e75a2a9b29edad Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Mon, 18 Sep 2023 20:56:22 +0200 Subject: [PATCH 1197/1444] New translations bns.md (Russian) --- .../current/stacks-academy/bns.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/stacks-academy/bns.md b/i18n/ru/docusaurus-plugin-content-docs/current/stacks-academy/bns.md index 8eb4f39376..6f7bb331ab 100644 --- a/i18n/ru/docusaurus-plugin-content-docs/current/stacks-academy/bns.md +++ b/i18n/ru/docusaurus-plugin-content-docs/current/stacks-academy/bns.md @@ -198,7 +198,7 @@ Because subdomain names are cheap, developers may be inclined to run subdomain r 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 and DID Standards BNS names are compliant with the emerging [Decentralized Identity Foundation](http://identity.foundation) protocol specification for decentralized identifiers (DIDs). From 4813a884c7fc9cc8de7fd10eb6d4a5d61192c588 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Mon, 18 Sep 2023 20:56:23 +0200 Subject: [PATCH 1198/1444] New translations bns.md (Turkish) --- .../current/stacks-academy/bns.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/i18n/tr/docusaurus-plugin-content-docs/current/stacks-academy/bns.md b/i18n/tr/docusaurus-plugin-content-docs/current/stacks-academy/bns.md index 8eb4f39376..6f7bb331ab 100644 --- a/i18n/tr/docusaurus-plugin-content-docs/current/stacks-academy/bns.md +++ b/i18n/tr/docusaurus-plugin-content-docs/current/stacks-academy/bns.md @@ -198,7 +198,7 @@ Because subdomain names are cheap, developers may be inclined to run subdomain r 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 and DID Standards BNS names are compliant with the emerging [Decentralized Identity Foundation](http://identity.foundation) protocol specification for decentralized identifiers (DIDs). From aa22469c73332cab6ecae089c91c3f77b54f23b3 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Mon, 18 Sep 2023 20:56:25 +0200 Subject: [PATCH 1199/1444] New translations bns.md (Chinese Simplified) --- .../current/stacks-academy/bns.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/stacks-academy/bns.md b/i18n/zh/docusaurus-plugin-content-docs/current/stacks-academy/bns.md index a217b1b38b..e4dc81662b 100644 --- a/i18n/zh/docusaurus-plugin-content-docs/current/stacks-academy/bns.md +++ b/i18n/zh/docusaurus-plugin-content-docs/current/stacks-academy/bns.md @@ -232,7 +232,7 @@ Because subdomain names are cheap, developers may be inclined to run subdomain r 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 +## 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. From d9df90e21a0404d5807090dc9efde1ecf0cd6133 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Mon, 18 Sep 2023 20:56:26 +0200 Subject: [PATCH 1200/1444] New translations bns.md (Vietnamese) --- .../current/stacks-academy/bns.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/i18n/vi/docusaurus-plugin-content-docs/current/stacks-academy/bns.md b/i18n/vi/docusaurus-plugin-content-docs/current/stacks-academy/bns.md index 8eb4f39376..6f7bb331ab 100644 --- a/i18n/vi/docusaurus-plugin-content-docs/current/stacks-academy/bns.md +++ b/i18n/vi/docusaurus-plugin-content-docs/current/stacks-academy/bns.md @@ -198,7 +198,7 @@ Because subdomain names are cheap, developers may be inclined to run subdomain r 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 and DID Standards BNS names are compliant with the emerging [Decentralized Identity Foundation](http://identity.foundation) protocol specification for decentralized identifiers (DIDs). From d52de3beaf5879a48a21eca7fde99a93d87ff288 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Mon, 18 Sep 2023 20:56:27 +0200 Subject: [PATCH 1201/1444] New translations bns.md (Portuguese, Brazilian) --- .../current/stacks-academy/bns.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/i18n/pt/docusaurus-plugin-content-docs/current/stacks-academy/bns.md b/i18n/pt/docusaurus-plugin-content-docs/current/stacks-academy/bns.md index 8d4d3b54f8..4e656499d3 100644 --- a/i18n/pt/docusaurus-plugin-content-docs/current/stacks-academy/bns.md +++ b/i18n/pt/docusaurus-plugin-content-docs/current/stacks-academy/bns.md @@ -195,7 +195,7 @@ Because subdomain names are cheap, developers may be inclined to run subdomain r 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 and DID Standards BNS names are compliant with the emerging [Decentralized Identity Foundation](http://identity.foundation) protocol specification for decentralized identifiers (DIDs). From ca1111e58c01d4ae6186795bc8037d33aae03a4b Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Mon, 18 Sep 2023 20:56:28 +0200 Subject: [PATCH 1202/1444] New translations bns.md (Indonesian) --- .../current/stacks-academy/bns.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/i18n/id/docusaurus-plugin-content-docs/current/stacks-academy/bns.md b/i18n/id/docusaurus-plugin-content-docs/current/stacks-academy/bns.md index 98c1e81afb..8fb80c7bdc 100644 --- a/i18n/id/docusaurus-plugin-content-docs/current/stacks-academy/bns.md +++ b/i18n/id/docusaurus-plugin-content-docs/current/stacks-academy/bns.md @@ -197,7 +197,7 @@ Karena nama subdomain murah, pengembang mungkin cenderung menjalankan pendaftar 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 and DID Standards BNS names are compliant with the emerging [Decentralized Identity Foundation](http://identity.foundation) protocol specification for decentralized identifiers (DIDs). @@ -230,7 +230,7 @@ Tidak semua nama akan memiliki DID yang menjadi kunci publik. Namun, nama yang d API RESTful sedang dalam pengembangan. -## Pengkodean DID untuk Subdomain +## DID Encoding for Subdomains Setiap nama dan subdomain di BNS memiliki DID. Pengkodean sedikit berbeda untuk subdomain, sehingga perangkat lunak dapat menentukan jalur kode mana yang harus diambil. From cd17f2f85c7b01f77fd6d55c53f4ad778c0b46f0 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Mon, 18 Sep 2023 20:56:29 +0200 Subject: [PATCH 1203/1444] New translations bns.md (Hindi) --- .../current/stacks-academy/bns.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/i18n/hi/docusaurus-plugin-content-docs/current/stacks-academy/bns.md b/i18n/hi/docusaurus-plugin-content-docs/current/stacks-academy/bns.md index 8eb4f39376..6f7bb331ab 100644 --- a/i18n/hi/docusaurus-plugin-content-docs/current/stacks-academy/bns.md +++ b/i18n/hi/docusaurus-plugin-content-docs/current/stacks-academy/bns.md @@ -198,7 +198,7 @@ Because subdomain names are cheap, developers may be inclined to run subdomain r 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 and DID Standards BNS names are compliant with the emerging [Decentralized Identity Foundation](http://identity.foundation) protocol specification for decentralized identifiers (DIDs). From 54405061dff72bb612bc1570ff731ef3d6f97f80 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Mon, 18 Sep 2023 21:56:20 +0200 Subject: [PATCH 1204/1444] Update source file bns.md --- docs/stacks-academy/bns.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/stacks-academy/bns.md b/docs/stacks-academy/bns.md index c1257855a9..134e8a6a37 100644 --- a/docs/stacks-academy/bns.md +++ b/docs/stacks-academy/bns.md @@ -330,7 +330,7 @@ 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 and DID Standards BNS names are compliant with the emerging [Decentralized Identity Foundation](http://identity.foundation) protocol From f264793436dbcbbe23e115697782477f8826a803 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sat, 7 Oct 2023 12:46:00 +0200 Subject: [PATCH 1205/1444] New translations authentication.md (Portuguese, Brazilian) --- .../current/stacks-academy/authentication.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/i18n/pt/docusaurus-plugin-content-docs/current/stacks-academy/authentication.md b/i18n/pt/docusaurus-plugin-content-docs/current/stacks-academy/authentication.md index 8152a401f9..fb6eaf52a9 100644 --- a/i18n/pt/docusaurus-plugin-content-docs/current/stacks-academy/authentication.md +++ b/i18n/pt/docusaurus-plugin-content-docs/current/stacks-academy/authentication.md @@ -1,18 +1,18 @@ --- -title: Authentication -description: Register and sign in users with identities on the Stacks blockchain +title: Autenticação +description: Registre e faça login de usuários com identidades no blockchain Stacks sidebar_position: 8 --- -## Introduction +## Introdução -This guide explains how authentication is performed on the Stacks blockchain. +Este guia explica como a autenticação é realizada na blockchain Stacks. -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. +A autenticação fornece uma maneira de os usuários se identificarem a um aplicativo, mantendo o controle total sobre suas credenciais e dados pessoais. 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. +Os usuários que se registrarem em seu aplicativo podem, posteriormente, autenticar em qualquer outro aplicativo com suporte para o sistema de nomes [de Blockchain](bns) e vice-versa. -## How it works +## Como isso funciona 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. From 82c155e1dcadcba4981026402bcdeddc490f6380 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sat, 7 Oct 2023 12:46:01 +0200 Subject: [PATCH 1206/1444] New translations docs.md (Portuguese, Brazilian) --- .../docusaurus-plugin-content-docs/current/contribute/docs.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/i18n/pt/docusaurus-plugin-content-docs/current/contribute/docs.md b/i18n/pt/docusaurus-plugin-content-docs/current/contribute/docs.md index b2fef628f9..ec1b1b0986 100644 --- a/i18n/pt/docusaurus-plugin-content-docs/current/contribute/docs.md +++ b/i18n/pt/docusaurus-plugin-content-docs/current/contribute/docs.md @@ -3,7 +3,7 @@ title: Contribute to docs description: Learn how this site is built, and how you can contribute to it. --- -## Introduction +## Introdução Thank you for your interest in contributing and helping make these docs as good as they can be. From f4f457504fc41458eea44c71c8cf7522b2d9c1da Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sat, 7 Oct 2023 12:46:02 +0200 Subject: [PATCH 1207/1444] New translations gaia-on-ec2.md (Portuguese, Brazilian) --- .../docusaurus-plugin-content-docs/current/gaia/gaia-on-ec2.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) 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 index 1ba301b42d..93fe3907e1 100644 --- 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 @@ -6,7 +6,7 @@ tags: - gaia --- -## Introduction +## Introdução 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. From 48281334e3aae9cbdd4c3320ea6eb4ef59b64076 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sat, 7 Oct 2023 12:46:04 +0200 Subject: [PATCH 1208/1444] New translations gaia.md (Portuguese, Brazilian) --- i18n/pt/docusaurus-plugin-content-docs/current/gaia/gaia.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/i18n/pt/docusaurus-plugin-content-docs/current/gaia/gaia.md b/i18n/pt/docusaurus-plugin-content-docs/current/gaia/gaia.md index e0cba7aa86..ec204e35ec 100644 --- a/i18n/pt/docusaurus-plugin-content-docs/current/gaia/gaia.md +++ b/i18n/pt/docusaurus-plugin-content-docs/current/gaia/gaia.md @@ -6,7 +6,7 @@ tags: - gaia --- -## Introduction +## Introdução Apps built with the Stacks blockchain can store off-chain data using a storage system called Gaia. From 921235daaf6f412d782220b4f201d8b3e41fca82 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sat, 7 Oct 2023 12:46:05 +0200 Subject: [PATCH 1209/1444] New translations digitalocean.md (Portuguese, Brazilian) --- .../current/nodes-and-miners/digitalocean.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) 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 index 15df918d04..7ed623b977 100644 --- 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 @@ -6,7 +6,7 @@ tags: - tutorial --- -## Introduction +## Introdução This is a step by step guide to deploy the [Stacks Blockchain](https://github.com/stacks-network/stacks-blockchain) on [DigitalOcean](https://digitalocean.com). From 17d9870772ea4675e6e49822cba90bf80c67876a Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sat, 7 Oct 2023 12:46:06 +0200 Subject: [PATCH 1210/1444] New translations miner-mainnet.md (Portuguese, Brazilian) --- .../current/nodes-and-miners/miner-mainnet.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) 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 index 5afd34c23f..5f4ad97634 100644 --- 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 @@ -6,7 +6,7 @@ tags: - tutorial --- -## Introduction +## Introdução For more on the technical details of mining, please review the [mining guide](../stacks-academy/mining) From cee6b1b6c2386dee5c333fe1d0c631ec9e6ff63d Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sat, 7 Oct 2023 12:46:06 +0200 Subject: [PATCH 1211/1444] New translations miner-testnet.md (Portuguese, Brazilian) --- .../current/nodes-and-miners/miner-testnet.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) 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 index c0a27e63d5..44eaba22bb 100644 --- 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 @@ -6,7 +6,7 @@ tags: - tutorial --- -## Introduction +## Introdução For more on the technical details of mining, please review the [mining guide](../stacks-academy/mining) From ad9b3f8d7774378439b0662d931b3474faf30fe9 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sat, 7 Oct 2023 12:46:08 +0200 Subject: [PATCH 1212/1444] New translations accounts.md (Portuguese, Brazilian) --- .../current/stacks-academy/accounts.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/i18n/pt/docusaurus-plugin-content-docs/current/stacks-academy/accounts.md b/i18n/pt/docusaurus-plugin-content-docs/current/stacks-academy/accounts.md index 8383157394..2923ba1b91 100644 --- a/i18n/pt/docusaurus-plugin-content-docs/current/stacks-academy/accounts.md +++ b/i18n/pt/docusaurus-plugin-content-docs/current/stacks-academy/accounts.md @@ -4,7 +4,7 @@ description: Guide to Stacks 2.0 accounts sidebar_position: 7 --- -## Introduction +## Introdução 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. From 51d8f64bf023c0ce9c1148ed466ca344044b3aab Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sat, 7 Oct 2023 12:46:09 +0200 Subject: [PATCH 1213/1444] New translations microblocks.md (Portuguese, Brazilian) --- .../current/stacks-academy/microblocks.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/i18n/pt/docusaurus-plugin-content-docs/current/stacks-academy/microblocks.md b/i18n/pt/docusaurus-plugin-content-docs/current/stacks-academy/microblocks.md index 9fd7b8209d..b178ff03aa 100644 --- a/i18n/pt/docusaurus-plugin-content-docs/current/stacks-academy/microblocks.md +++ b/i18n/pt/docusaurus-plugin-content-docs/current/stacks-academy/microblocks.md @@ -4,7 +4,7 @@ description: Guide to Stacks Microblocks sidebar_position: 5 --- -## Introduction +## Introdução Microblocks are a protocol-level feature of the Stacks blockchain that solve the technical challenge of transaction latency. From 7589d603f424b63dec7d7cd8df7a5b6609d4e88b Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sat, 7 Oct 2023 12:46:10 +0200 Subject: [PATCH 1214/1444] New translations mining.md (Portuguese, Brazilian) --- .../current/stacks-academy/mining.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/i18n/pt/docusaurus-plugin-content-docs/current/stacks-academy/mining.md b/i18n/pt/docusaurus-plugin-content-docs/current/stacks-academy/mining.md index 78a0711ebd..27c83c32fa 100644 --- a/i18n/pt/docusaurus-plugin-content-docs/current/stacks-academy/mining.md +++ b/i18n/pt/docusaurus-plugin-content-docs/current/stacks-academy/mining.md @@ -4,7 +4,7 @@ description: A guide to mining on Stacks 2.0 sidebar_position: 4 --- -## Introduction +## Introdução This guide highlights some technical details related to mining on the Stacks 2.0 network. From 90091ff04d3fbc35ad749a7ca4e33b7f95d77589 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sat, 7 Oct 2023 12:46:11 +0200 Subject: [PATCH 1215/1444] New translations stacking.md (Portuguese, Brazilian) --- .../current/stacks-academy/stacking.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/i18n/pt/docusaurus-plugin-content-docs/current/stacks-academy/stacking.md b/i18n/pt/docusaurus-plugin-content-docs/current/stacks-academy/stacking.md index 20e5d5746e..3062c395ba 100644 --- a/i18n/pt/docusaurus-plugin-content-docs/current/stacks-academy/stacking.md +++ b/i18n/pt/docusaurus-plugin-content-docs/current/stacks-academy/stacking.md @@ -4,7 +4,7 @@ description: Introduction to the reward mechanism of Proof-of-Transfer sidebar_position: 11 --- -## Introduction +## Introdução 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. From 26ae2da682d83ac9b556c708e71f35bf89dfae4e Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sat, 7 Oct 2023 12:46:12 +0200 Subject: [PATCH 1216/1444] New translations transactions.md (Portuguese, Brazilian) --- .../current/stacks-academy/transactions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/i18n/pt/docusaurus-plugin-content-docs/current/stacks-academy/transactions.md b/i18n/pt/docusaurus-plugin-content-docs/current/stacks-academy/transactions.md index ba6b18f0f7..82aea437f9 100644 --- a/i18n/pt/docusaurus-plugin-content-docs/current/stacks-academy/transactions.md +++ b/i18n/pt/docusaurus-plugin-content-docs/current/stacks-academy/transactions.md @@ -4,7 +4,7 @@ description: Guide to Stacks 2.0 transactions sidebar_position: 9 --- -## Introduction +## Introdução 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. From 2e580d9b36388c6694ee2f4212a202ba08d87853 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sat, 7 Oct 2023 12:46:13 +0200 Subject: [PATCH 1217/1444] New translations stacks-blockchain-api.md (Portuguese, Brazilian) --- .../current/stacks-academy/stacks-blockchain-api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/i18n/pt/docusaurus-plugin-content-docs/current/stacks-academy/stacks-blockchain-api.md b/i18n/pt/docusaurus-plugin-content-docs/current/stacks-academy/stacks-blockchain-api.md index ad9bb1822e..80e7463540 100644 --- a/i18n/pt/docusaurus-plugin-content-docs/current/stacks-academy/stacks-blockchain-api.md +++ b/i18n/pt/docusaurus-plugin-content-docs/current/stacks-academy/stacks-blockchain-api.md @@ -4,7 +4,7 @@ description: Interacting with the Stacks 2.0 Blockchain via API sidebar_position: 6 --- -## Introduction +## Introdução 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/). ::: From fbf5b835b8929a06aa626cd88d0a3fe832747578 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sat, 7 Oct 2023 12:46:14 +0200 Subject: [PATCH 1218/1444] New translations bns-contract.md (Portuguese, Brazilian) --- .../current/clarity/noteworthy-contracts/bns-contract.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/i18n/pt/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/bns-contract.md b/i18n/pt/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/bns-contract.md index 13a0198924..25fa47305a 100644 --- a/i18n/pt/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/bns-contract.md +++ b/i18n/pt/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/bns-contract.md @@ -5,7 +5,7 @@ description: The Bitcoin Name System. ![](/img/satoshi-btc.png) -## Introduction +## Introdução The Bitcoin Name System (BNS) is implemented as a smart contract using Clarity. From fc91af28f48cf61c0edd690156f99b2640cf4800 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sat, 7 Oct 2023 12:46:15 +0200 Subject: [PATCH 1219/1444] New translations xbtc.md (Portuguese, Brazilian) --- .../current/clarity/noteworthy-contracts/xbtc.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/i18n/pt/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/xbtc.md b/i18n/pt/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/xbtc.md index e535dcf260..e7ec483a54 100644 --- a/i18n/pt/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/xbtc.md +++ b/i18n/pt/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/xbtc.md @@ -5,7 +5,7 @@ description: Wrapped BTC on Stacks ![](/img/xbtc-icon.webp) -## Introduction +## Introdução [Wrapped.com](https://www.wrapped.com) has brought Bitcoin (xBTC) to the Stacks ecosystem. From d348c2fc275d9f598335e053d24d79ca8c787943 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sat, 7 Oct 2023 12:46:16 +0200 Subject: [PATCH 1220/1444] New translations stacking-contract.md (Portuguese, Brazilian) --- .../current/clarity/noteworthy-contracts/stacking-contract.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/i18n/pt/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/stacking-contract.md b/i18n/pt/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/stacking-contract.md index c0027256cd..f58c4a86bd 100644 --- a/i18n/pt/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/stacking-contract.md +++ b/i18n/pt/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/stacking-contract.md @@ -4,7 +4,7 @@ description: See a detailed list of all functions and error codes of the Stackin sidebar_position: 6 --- -## Introduction +## Introdução 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). From d8ae761bd9ee428a21e577f93478c51c4baddc5a Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Sat, 7 Oct 2023 14:20:31 +0200 Subject: [PATCH 1221/1444] New translations authentication.md (Portuguese, Brazilian) --- .../current/stacks-academy/authentication.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/i18n/pt/docusaurus-plugin-content-docs/current/stacks-academy/authentication.md b/i18n/pt/docusaurus-plugin-content-docs/current/stacks-academy/authentication.md index fb6eaf52a9..c9a62956c1 100644 --- a/i18n/pt/docusaurus-plugin-content-docs/current/stacks-academy/authentication.md +++ b/i18n/pt/docusaurus-plugin-content-docs/current/stacks-academy/authentication.md @@ -14,9 +14,9 @@ Os usuários que se registrarem em seu aplicativo podem, posteriormente, autenti ## Como isso funciona -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. +O fluxo de autenticação com Stacks é semelhante ao fluxo típico do servidor cliente-servidor usado por serviços centralizados (por exemplo, OAuth). No entanto, com Stacks o fluxo de autenticação acontece totalmente no lado do cliente. -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. +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. O aplicativo de solicitação envia ao autenticador um token `authRequest`. Assim que um usuário aprova a autenticação, o autenticador responde ao aplicativo com um token `authResponse`. 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. From 770e1f52aa038d64101e7fc100072f2dd2fa2ba2 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Thu, 19 Oct 2023 16:13:45 +0200 Subject: [PATCH 1222/1444] New translations testnet.md (French) --- .../current/stacks-academy/testnet.md | 14 ++++++++++++-- 1 file changed, 12 insertions(+), 2 deletions(-) diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/stacks-academy/testnet.md b/i18n/fr/docusaurus-plugin-content-docs/current/stacks-academy/testnet.md index f8b9f03df2..da2e561fd1 100644 --- a/i18n/fr/docusaurus-plugin-content-docs/current/stacks-academy/testnet.md +++ b/i18n/fr/docusaurus-plugin-content-docs/current/stacks-academy/testnet.md @@ -10,9 +10,13 @@ The testnet is a separate blockchain from the Stacks mainnet analogous to a stag 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 +### Faucets -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). +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. @@ -24,6 +28,12 @@ You can also try out [Stacking](./stacking) by clicking on `I want to stack`. 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: From 87695d2b2e278a3f5c8d1542412e03e71a3fe214 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Thu, 19 Oct 2023 16:13:46 +0200 Subject: [PATCH 1223/1444] New translations get-sats-per-stx.md (French) --- .../current/cookbook/get-sats-per-stx.md | 27 +++++++++++++++++++ 1 file changed, 27 insertions(+) create mode 100644 i18n/fr/docusaurus-plugin-content-docs/current/cookbook/get-sats-per-stx.md diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/cookbook/get-sats-per-stx.md b/i18n/fr/docusaurus-plugin-content-docs/current/cookbook/get-sats-per-stx.md new file mode 100644 index 0000000000..d6ef942f94 --- /dev/null +++ b/i18n/fr/docusaurus-plugin-content-docs/current/cookbook/get-sats-per-stx.md @@ -0,0 +1,27 @@ +--- +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. From 8fd8c240e1cd7fd884cf4e48727170f954a22401 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Thu, 19 Oct 2023 16:13:47 +0200 Subject: [PATCH 1224/1444] New translations testnet.md (Spanish) --- .../current/stacks-academy/testnet.md | 14 ++++++++++++-- 1 file changed, 12 insertions(+), 2 deletions(-) diff --git a/i18n/es/docusaurus-plugin-content-docs/current/stacks-academy/testnet.md b/i18n/es/docusaurus-plugin-content-docs/current/stacks-academy/testnet.md index 214b327dd8..9e2db6a8dd 100644 --- a/i18n/es/docusaurus-plugin-content-docs/current/stacks-academy/testnet.md +++ b/i18n/es/docusaurus-plugin-content-docs/current/stacks-academy/testnet.md @@ -10,9 +10,13 @@ The testnet is a separate blockchain from the Stacks mainnet analogous to a stag 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 +### Faucets -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). +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. @@ -24,6 +28,12 @@ You can also try out [Stacking](./stacking) by clicking on `I want to stack`. 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: From bcea1914f1dd619d8e3e0b8a08c849a4ca913b49 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Thu, 19 Oct 2023 16:13:48 +0200 Subject: [PATCH 1225/1444] New translations get-sats-per-stx.md (Spanish) --- .../current/cookbook/get-sats-per-stx.md | 27 +++++++++++++++++++ 1 file changed, 27 insertions(+) create mode 100644 i18n/es/docusaurus-plugin-content-docs/current/cookbook/get-sats-per-stx.md diff --git a/i18n/es/docusaurus-plugin-content-docs/current/cookbook/get-sats-per-stx.md b/i18n/es/docusaurus-plugin-content-docs/current/cookbook/get-sats-per-stx.md new file mode 100644 index 0000000000..d6ef942f94 --- /dev/null +++ b/i18n/es/docusaurus-plugin-content-docs/current/cookbook/get-sats-per-stx.md @@ -0,0 +1,27 @@ +--- +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. From 40ec45a80f8d4f9ee0228f9ca6c8e039b2ee5a46 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Thu, 19 Oct 2023 16:13:50 +0200 Subject: [PATCH 1226/1444] New translations testnet.md (German) --- .../current/stacks-academy/testnet.md | 14 ++++++++++++-- 1 file changed, 12 insertions(+), 2 deletions(-) diff --git a/i18n/de/docusaurus-plugin-content-docs/current/stacks-academy/testnet.md b/i18n/de/docusaurus-plugin-content-docs/current/stacks-academy/testnet.md index f8b9f03df2..da2e561fd1 100644 --- a/i18n/de/docusaurus-plugin-content-docs/current/stacks-academy/testnet.md +++ b/i18n/de/docusaurus-plugin-content-docs/current/stacks-academy/testnet.md @@ -10,9 +10,13 @@ The testnet is a separate blockchain from the Stacks mainnet analogous to a stag 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 +### Faucets -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). +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. @@ -24,6 +28,12 @@ You can also try out [Stacking](./stacking) by clicking on `I want to stack`. 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: From e932334b8c688f758c19407d9edd3a580d5c95ee Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Thu, 19 Oct 2023 16:13:50 +0200 Subject: [PATCH 1227/1444] New translations get-sats-per-stx.md (German) --- .../current/cookbook/get-sats-per-stx.md | 27 +++++++++++++++++++ 1 file changed, 27 insertions(+) create mode 100644 i18n/de/docusaurus-plugin-content-docs/current/cookbook/get-sats-per-stx.md diff --git a/i18n/de/docusaurus-plugin-content-docs/current/cookbook/get-sats-per-stx.md b/i18n/de/docusaurus-plugin-content-docs/current/cookbook/get-sats-per-stx.md new file mode 100644 index 0000000000..d6ef942f94 --- /dev/null +++ b/i18n/de/docusaurus-plugin-content-docs/current/cookbook/get-sats-per-stx.md @@ -0,0 +1,27 @@ +--- +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. From ffc02b7611cfaa325c609596a5af0ac577f0102d Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Thu, 19 Oct 2023 16:13:51 +0200 Subject: [PATCH 1228/1444] New translations testnet.md (Japanese) --- .../current/stacks-academy/testnet.md | 14 ++++++++++++-- 1 file changed, 12 insertions(+), 2 deletions(-) diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/stacks-academy/testnet.md b/i18n/ja/docusaurus-plugin-content-docs/current/stacks-academy/testnet.md index f8b9f03df2..da2e561fd1 100644 --- a/i18n/ja/docusaurus-plugin-content-docs/current/stacks-academy/testnet.md +++ b/i18n/ja/docusaurus-plugin-content-docs/current/stacks-academy/testnet.md @@ -10,9 +10,13 @@ The testnet is a separate blockchain from the Stacks mainnet analogous to a stag 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 +### Faucets -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). +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. @@ -24,6 +28,12 @@ You can also try out [Stacking](./stacking) by clicking on `I want to stack`. 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: From 7a8ca2dae949d60952e79d1ba6a2cf01ac816356 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Thu, 19 Oct 2023 16:13:52 +0200 Subject: [PATCH 1229/1444] New translations get-sats-per-stx.md (Japanese) --- .../current/cookbook/get-sats-per-stx.md | 27 +++++++++++++++++++ 1 file changed, 27 insertions(+) create mode 100644 i18n/ja/docusaurus-plugin-content-docs/current/cookbook/get-sats-per-stx.md diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/cookbook/get-sats-per-stx.md b/i18n/ja/docusaurus-plugin-content-docs/current/cookbook/get-sats-per-stx.md new file mode 100644 index 0000000000..d6ef942f94 --- /dev/null +++ b/i18n/ja/docusaurus-plugin-content-docs/current/cookbook/get-sats-per-stx.md @@ -0,0 +1,27 @@ +--- +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. From ad3725c20a73feff94afda72f76b53b8c7d1e5f1 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Thu, 19 Oct 2023 16:13:53 +0200 Subject: [PATCH 1230/1444] New translations testnet.md (Korean) --- .../current/stacks-academy/testnet.md | 14 ++++++++++++-- 1 file changed, 12 insertions(+), 2 deletions(-) diff --git a/i18n/ko/docusaurus-plugin-content-docs/current/stacks-academy/testnet.md b/i18n/ko/docusaurus-plugin-content-docs/current/stacks-academy/testnet.md index f8b9f03df2..da2e561fd1 100644 --- a/i18n/ko/docusaurus-plugin-content-docs/current/stacks-academy/testnet.md +++ b/i18n/ko/docusaurus-plugin-content-docs/current/stacks-academy/testnet.md @@ -10,9 +10,13 @@ The testnet is a separate blockchain from the Stacks mainnet analogous to a stag 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 +### Faucets -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). +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. @@ -24,6 +28,12 @@ You can also try out [Stacking](./stacking) by clicking on `I want to stack`. 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: From 3a12344b6549995d4f5666492a90dca1aab86035 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Thu, 19 Oct 2023 16:13:54 +0200 Subject: [PATCH 1231/1444] New translations get-sats-per-stx.md (Korean) --- .../current/cookbook/get-sats-per-stx.md | 27 +++++++++++++++++++ 1 file changed, 27 insertions(+) create mode 100644 i18n/ko/docusaurus-plugin-content-docs/current/cookbook/get-sats-per-stx.md diff --git a/i18n/ko/docusaurus-plugin-content-docs/current/cookbook/get-sats-per-stx.md b/i18n/ko/docusaurus-plugin-content-docs/current/cookbook/get-sats-per-stx.md new file mode 100644 index 0000000000..d6ef942f94 --- /dev/null +++ b/i18n/ko/docusaurus-plugin-content-docs/current/cookbook/get-sats-per-stx.md @@ -0,0 +1,27 @@ +--- +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. From 2c858967efede27b18a37fc2a6efe570f58fc689 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Thu, 19 Oct 2023 16:13:55 +0200 Subject: [PATCH 1232/1444] New translations testnet.md (Russian) --- .../current/stacks-academy/testnet.md | 14 ++++++++++++-- 1 file changed, 12 insertions(+), 2 deletions(-) diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/stacks-academy/testnet.md b/i18n/ru/docusaurus-plugin-content-docs/current/stacks-academy/testnet.md index f8b9f03df2..da2e561fd1 100644 --- a/i18n/ru/docusaurus-plugin-content-docs/current/stacks-academy/testnet.md +++ b/i18n/ru/docusaurus-plugin-content-docs/current/stacks-academy/testnet.md @@ -10,9 +10,13 @@ The testnet is a separate blockchain from the Stacks mainnet analogous to a stag 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 +### Faucets -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). +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. @@ -24,6 +28,12 @@ You can also try out [Stacking](./stacking) by clicking on `I want to stack`. 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: From 28db7a27890cc8f90df4acd8864d1e9caaf24a1d Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Thu, 19 Oct 2023 16:13:56 +0200 Subject: [PATCH 1233/1444] New translations get-sats-per-stx.md (Russian) --- .../current/cookbook/get-sats-per-stx.md | 27 +++++++++++++++++++ 1 file changed, 27 insertions(+) create mode 100644 i18n/ru/docusaurus-plugin-content-docs/current/cookbook/get-sats-per-stx.md diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/cookbook/get-sats-per-stx.md b/i18n/ru/docusaurus-plugin-content-docs/current/cookbook/get-sats-per-stx.md new file mode 100644 index 0000000000..d6ef942f94 --- /dev/null +++ b/i18n/ru/docusaurus-plugin-content-docs/current/cookbook/get-sats-per-stx.md @@ -0,0 +1,27 @@ +--- +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. From 83fbcddaea90fb24f9cc53f595a521b96ce0bd8f Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Thu, 19 Oct 2023 16:13:57 +0200 Subject: [PATCH 1234/1444] New translations testnet.md (Turkish) --- .../current/stacks-academy/testnet.md | 14 ++++++++++++-- 1 file changed, 12 insertions(+), 2 deletions(-) diff --git a/i18n/tr/docusaurus-plugin-content-docs/current/stacks-academy/testnet.md b/i18n/tr/docusaurus-plugin-content-docs/current/stacks-academy/testnet.md index f8b9f03df2..da2e561fd1 100644 --- a/i18n/tr/docusaurus-plugin-content-docs/current/stacks-academy/testnet.md +++ b/i18n/tr/docusaurus-plugin-content-docs/current/stacks-academy/testnet.md @@ -10,9 +10,13 @@ The testnet is a separate blockchain from the Stacks mainnet analogous to a stag 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 +### Faucets -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). +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. @@ -24,6 +28,12 @@ You can also try out [Stacking](./stacking) by clicking on `I want to stack`. 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: From 7171bf81f85e333d6009f3ec2b7ca8884039bfa5 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Thu, 19 Oct 2023 16:13:58 +0200 Subject: [PATCH 1235/1444] New translations get-sats-per-stx.md (Turkish) --- .../current/cookbook/get-sats-per-stx.md | 27 +++++++++++++++++++ 1 file changed, 27 insertions(+) create mode 100644 i18n/tr/docusaurus-plugin-content-docs/current/cookbook/get-sats-per-stx.md diff --git a/i18n/tr/docusaurus-plugin-content-docs/current/cookbook/get-sats-per-stx.md b/i18n/tr/docusaurus-plugin-content-docs/current/cookbook/get-sats-per-stx.md new file mode 100644 index 0000000000..d6ef942f94 --- /dev/null +++ b/i18n/tr/docusaurus-plugin-content-docs/current/cookbook/get-sats-per-stx.md @@ -0,0 +1,27 @@ +--- +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. From bd6bc4078e966f8fbdb33fc1a37d95621f965127 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Thu, 19 Oct 2023 16:13:59 +0200 Subject: [PATCH 1236/1444] New translations testnet.md (Chinese Simplified) --- .../current/stacks-academy/testnet.md | 14 ++++++++++++-- 1 file changed, 12 insertions(+), 2 deletions(-) diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/stacks-academy/testnet.md b/i18n/zh/docusaurus-plugin-content-docs/current/stacks-academy/testnet.md index f8b9f03df2..da2e561fd1 100644 --- a/i18n/zh/docusaurus-plugin-content-docs/current/stacks-academy/testnet.md +++ b/i18n/zh/docusaurus-plugin-content-docs/current/stacks-academy/testnet.md @@ -10,9 +10,13 @@ The testnet is a separate blockchain from the Stacks mainnet analogous to a stag 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 +### Faucets -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). +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. @@ -24,6 +28,12 @@ You can also try out [Stacking](./stacking) by clicking on `I want to stack`. 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: From 85d3dbde6c0a54e46fe5cdb786d8193e2a4c744b Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Thu, 19 Oct 2023 16:14:00 +0200 Subject: [PATCH 1237/1444] New translations get-sats-per-stx.md (Chinese Simplified) --- .../current/cookbook/get-sats-per-stx.md | 27 +++++++++++++++++++ 1 file changed, 27 insertions(+) create mode 100644 i18n/zh/docusaurus-plugin-content-docs/current/cookbook/get-sats-per-stx.md diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/cookbook/get-sats-per-stx.md b/i18n/zh/docusaurus-plugin-content-docs/current/cookbook/get-sats-per-stx.md new file mode 100644 index 0000000000..d6ef942f94 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/current/cookbook/get-sats-per-stx.md @@ -0,0 +1,27 @@ +--- +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. From c648d62c7cc6b32653b7ce8f4558ca204f4e89b5 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Thu, 19 Oct 2023 16:14:01 +0200 Subject: [PATCH 1238/1444] New translations testnet.md (Vietnamese) --- .../current/stacks-academy/testnet.md | 14 ++++++++++++-- 1 file changed, 12 insertions(+), 2 deletions(-) diff --git a/i18n/vi/docusaurus-plugin-content-docs/current/stacks-academy/testnet.md b/i18n/vi/docusaurus-plugin-content-docs/current/stacks-academy/testnet.md index f8b9f03df2..da2e561fd1 100644 --- a/i18n/vi/docusaurus-plugin-content-docs/current/stacks-academy/testnet.md +++ b/i18n/vi/docusaurus-plugin-content-docs/current/stacks-academy/testnet.md @@ -10,9 +10,13 @@ The testnet is a separate blockchain from the Stacks mainnet analogous to a stag 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 +### Faucets -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). +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. @@ -24,6 +28,12 @@ You can also try out [Stacking](./stacking) by clicking on `I want to stack`. 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: From a0cfc20173b2fc02ea3caa0bf3bc03b4ecde8ee4 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Thu, 19 Oct 2023 16:14:02 +0200 Subject: [PATCH 1239/1444] New translations get-sats-per-stx.md (Vietnamese) --- .../current/cookbook/get-sats-per-stx.md | 27 +++++++++++++++++++ 1 file changed, 27 insertions(+) create mode 100644 i18n/vi/docusaurus-plugin-content-docs/current/cookbook/get-sats-per-stx.md diff --git a/i18n/vi/docusaurus-plugin-content-docs/current/cookbook/get-sats-per-stx.md b/i18n/vi/docusaurus-plugin-content-docs/current/cookbook/get-sats-per-stx.md new file mode 100644 index 0000000000..d6ef942f94 --- /dev/null +++ b/i18n/vi/docusaurus-plugin-content-docs/current/cookbook/get-sats-per-stx.md @@ -0,0 +1,27 @@ +--- +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. From 8724be383eef9a0be3c4d0472e02159219d777a0 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Thu, 19 Oct 2023 16:14:03 +0200 Subject: [PATCH 1240/1444] New translations testnet.md (Portuguese, Brazilian) --- .../current/stacks-academy/testnet.md | 14 ++++++++++++-- 1 file changed, 12 insertions(+), 2 deletions(-) diff --git a/i18n/pt/docusaurus-plugin-content-docs/current/stacks-academy/testnet.md b/i18n/pt/docusaurus-plugin-content-docs/current/stacks-academy/testnet.md index f8b9f03df2..da2e561fd1 100644 --- a/i18n/pt/docusaurus-plugin-content-docs/current/stacks-academy/testnet.md +++ b/i18n/pt/docusaurus-plugin-content-docs/current/stacks-academy/testnet.md @@ -10,9 +10,13 @@ The testnet is a separate blockchain from the Stacks mainnet analogous to a stag 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 +### Faucets -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). +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. @@ -24,6 +28,12 @@ You can also try out [Stacking](./stacking) by clicking on `I want to stack`. 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: From ab42af2bd8415f5e1ae5c058c138e7b2b5678dd5 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Thu, 19 Oct 2023 16:14:04 +0200 Subject: [PATCH 1241/1444] New translations get-sats-per-stx.md (Portuguese, Brazilian) --- .../current/cookbook/get-sats-per-stx.md | 27 +++++++++++++++++++ 1 file changed, 27 insertions(+) create mode 100644 i18n/pt/docusaurus-plugin-content-docs/current/cookbook/get-sats-per-stx.md diff --git a/i18n/pt/docusaurus-plugin-content-docs/current/cookbook/get-sats-per-stx.md b/i18n/pt/docusaurus-plugin-content-docs/current/cookbook/get-sats-per-stx.md new file mode 100644 index 0000000000..d6ef942f94 --- /dev/null +++ b/i18n/pt/docusaurus-plugin-content-docs/current/cookbook/get-sats-per-stx.md @@ -0,0 +1,27 @@ +--- +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. From 07a002ec378ab163ed7a3bfeb7e686dafc54ad09 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Thu, 19 Oct 2023 16:14:05 +0200 Subject: [PATCH 1242/1444] New translations testnet.md (Indonesian) --- .../current/stacks-academy/testnet.md | 14 ++++++++++++-- 1 file changed, 12 insertions(+), 2 deletions(-) diff --git a/i18n/id/docusaurus-plugin-content-docs/current/stacks-academy/testnet.md b/i18n/id/docusaurus-plugin-content-docs/current/stacks-academy/testnet.md index 9714abd1bf..afed374857 100644 --- a/i18n/id/docusaurus-plugin-content-docs/current/stacks-academy/testnet.md +++ b/i18n/id/docusaurus-plugin-content-docs/current/stacks-academy/testnet.md @@ -10,9 +10,13 @@ The testnet is a separate blockchain from the Stacks mainnet analogous to a stag 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 +### Faucets -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). +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. @@ -24,6 +28,12 @@ You can also try out [Stacking](./stacking) by clicking on `I want to stack`. 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) + ### API testnet The hosted Stacks Blockchain API for the testnet is available at this base URL: From 4290e3f0baf7c363dd6b0129538235919d2cbc54 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Thu, 19 Oct 2023 16:14:06 +0200 Subject: [PATCH 1243/1444] New translations get-sats-per-stx.md (Indonesian) --- .../current/cookbook/get-sats-per-stx.md | 27 +++++++++++++++++++ 1 file changed, 27 insertions(+) create mode 100644 i18n/id/docusaurus-plugin-content-docs/current/cookbook/get-sats-per-stx.md diff --git a/i18n/id/docusaurus-plugin-content-docs/current/cookbook/get-sats-per-stx.md b/i18n/id/docusaurus-plugin-content-docs/current/cookbook/get-sats-per-stx.md new file mode 100644 index 0000000000..d6ef942f94 --- /dev/null +++ b/i18n/id/docusaurus-plugin-content-docs/current/cookbook/get-sats-per-stx.md @@ -0,0 +1,27 @@ +--- +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. From bd9890fa4ae28d7a3e17a5ab864539eade639a24 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Thu, 19 Oct 2023 16:14:07 +0200 Subject: [PATCH 1244/1444] New translations testnet.md (Hindi) --- .../current/stacks-academy/testnet.md | 14 ++++++++++++-- 1 file changed, 12 insertions(+), 2 deletions(-) diff --git a/i18n/hi/docusaurus-plugin-content-docs/current/stacks-academy/testnet.md b/i18n/hi/docusaurus-plugin-content-docs/current/stacks-academy/testnet.md index f8b9f03df2..da2e561fd1 100644 --- a/i18n/hi/docusaurus-plugin-content-docs/current/stacks-academy/testnet.md +++ b/i18n/hi/docusaurus-plugin-content-docs/current/stacks-academy/testnet.md @@ -10,9 +10,13 @@ The testnet is a separate blockchain from the Stacks mainnet analogous to a stag 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 +### Faucets -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). +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. @@ -24,6 +28,12 @@ You can also try out [Stacking](./stacking) by clicking on `I want to stack`. 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: From f82de5221de218f20a358a0364f528432fdd55c4 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Thu, 19 Oct 2023 16:14:08 +0200 Subject: [PATCH 1245/1444] New translations get-sats-per-stx.md (Hindi) --- .../current/cookbook/get-sats-per-stx.md | 27 +++++++++++++++++++ 1 file changed, 27 insertions(+) create mode 100644 i18n/hi/docusaurus-plugin-content-docs/current/cookbook/get-sats-per-stx.md diff --git a/i18n/hi/docusaurus-plugin-content-docs/current/cookbook/get-sats-per-stx.md b/i18n/hi/docusaurus-plugin-content-docs/current/cookbook/get-sats-per-stx.md new file mode 100644 index 0000000000..d6ef942f94 --- /dev/null +++ b/i18n/hi/docusaurus-plugin-content-docs/current/cookbook/get-sats-per-stx.md @@ -0,0 +1,27 @@ +--- +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. From 037c5a9f2c53932458c29bab184cccaf9bd2d408 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Thu, 19 Oct 2023 17:31:54 +0200 Subject: [PATCH 1246/1444] Update source file get-sats-per-stx.md --- docs/cookbook/get-sats-per-stx.md | 27 +++++++++++++++++++++++++++ 1 file changed, 27 insertions(+) create mode 100644 docs/cookbook/get-sats-per-stx.md diff --git a/docs/cookbook/get-sats-per-stx.md b/docs/cookbook/get-sats-per-stx.md new file mode 100644 index 0000000000..d6ef942f94 --- /dev/null +++ b/docs/cookbook/get-sats-per-stx.md @@ -0,0 +1,27 @@ +--- +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. From 13a7c602fda494c94ee8db225c896b3eec992897 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Thu, 19 Oct 2023 17:32:06 +0200 Subject: [PATCH 1247/1444] Update source file testnet.md --- docs/stacks-academy/testnet.md | 14 ++++++++++++-- 1 file changed, 12 insertions(+), 2 deletions(-) diff --git a/docs/stacks-academy/testnet.md b/docs/stacks-academy/testnet.md index f8b9f03df2..da2e561fd1 100644 --- a/docs/stacks-academy/testnet.md +++ b/docs/stacks-academy/testnet.md @@ -10,9 +10,13 @@ The testnet is a separate blockchain from the Stacks mainnet analogous to a stag 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 +### Faucets -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). +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. @@ -24,6 +28,12 @@ You can also try out [Stacking](./stacking) by clicking on `I want to stack`. 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: From 72682e73b9863e145e808e1a7e4ef8b69b78b257 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Thu, 26 Oct 2023 20:07:42 +0200 Subject: [PATCH 1248/1444] New translations authentication.md (French) --- .../current/stacks-academy/authentication.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/stacks-academy/authentication.md b/i18n/fr/docusaurus-plugin-content-docs/current/stacks-academy/authentication.md index b135f2f9ce..eb5f68eaa4 100644 --- a/i18n/fr/docusaurus-plugin-content-docs/current/stacks-academy/authentication.md +++ b/i18n/fr/docusaurus-plugin-content-docs/current/stacks-academy/authentication.md @@ -18,7 +18,7 @@ Le flux d'authentification avec Stacks est similaire au flux typique client-serv 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. +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. 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é : From 757c4f0aee15daec224ddc77820161b09849b101 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Thu, 26 Oct 2023 20:07:43 +0200 Subject: [PATCH 1249/1444] New translations bns.md (French) --- .../current/stacks-academy/bns.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/stacks-academy/bns.md b/i18n/fr/docusaurus-plugin-content-docs/current/stacks-academy/bns.md index cbe802715e..524b51e4fb 100644 --- a/i18n/fr/docusaurus-plugin-content-docs/current/stacks-academy/bns.md +++ b/i18n/fr/docusaurus-plugin-content-docs/current/stacks-academy/bns.md @@ -32,7 +32,7 @@ Quelles sortes de choses voulons-nous être vraies en ce qui concerne les noms? - **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. +- En PGP, les noms sont des clés d'identification. They are globally unique and cryptographically owned, but not human-readable. 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: From 3b4f83a23019b799d16cd61cad06a0b1a4eebdc7 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Thu, 26 Oct 2023 20:07:45 +0200 Subject: [PATCH 1250/1444] New translations authentication.md (Spanish) --- .../current/stacks-academy/authentication.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/i18n/es/docusaurus-plugin-content-docs/current/stacks-academy/authentication.md b/i18n/es/docusaurus-plugin-content-docs/current/stacks-academy/authentication.md index cefd1b2907..ae4363179c 100644 --- a/i18n/es/docusaurus-plugin-content-docs/current/stacks-academy/authentication.md +++ b/i18n/es/docusaurus-plugin-content-docs/current/stacks-academy/authentication.md @@ -18,7 +18,7 @@ El flujo de autenticación con Stacks es similar al típico flujo cliente-servid 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. +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. 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: From 57ef4856cdd72f602f48e11232bcecb2e0c3812e Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Thu, 26 Oct 2023 20:07:46 +0200 Subject: [PATCH 1251/1444] New translations bns.md (Spanish) --- .../current/stacks-academy/bns.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/i18n/es/docusaurus-plugin-content-docs/current/stacks-academy/bns.md b/i18n/es/docusaurus-plugin-content-docs/current/stacks-academy/bns.md index a72b5ec6d0..b5a60f8f4a 100644 --- a/i18n/es/docusaurus-plugin-content-docs/current/stacks-academy/bns.md +++ b/i18n/es/docusaurus-plugin-content-docs/current/stacks-academy/bns.md @@ -32,7 +32,7 @@ We rely on name systems in everyday life, and they play a critical role in many - **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. +- En PGP, los nombres son identificadores de clave. They are globally unique and cryptographically owned, but not human-readable. 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: From 0a1f460fcc080d4c4e7e0c841889629e91dec4d0 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Thu, 26 Oct 2023 20:07:47 +0200 Subject: [PATCH 1252/1444] New translations authentication.md (German) --- .../current/stacks-academy/authentication.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/i18n/de/docusaurus-plugin-content-docs/current/stacks-academy/authentication.md b/i18n/de/docusaurus-plugin-content-docs/current/stacks-academy/authentication.md index 10ac692bb9..9e854e54f2 100644 --- a/i18n/de/docusaurus-plugin-content-docs/current/stacks-academy/authentication.md +++ b/i18n/de/docusaurus-plugin-content-docs/current/stacks-academy/authentication.md @@ -18,7 +18,7 @@ The authentication flow with Stacks is similar to the typical client-server flow 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. +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: From a395f91e30a7640aa88a5e3af0787829b78ea4ae Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Thu, 26 Oct 2023 20:07:49 +0200 Subject: [PATCH 1253/1444] New translations bns.md (German) --- .../current/stacks-academy/bns.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/i18n/de/docusaurus-plugin-content-docs/current/stacks-academy/bns.md b/i18n/de/docusaurus-plugin-content-docs/current/stacks-academy/bns.md index 6f7bb331ab..9f88fabff4 100644 --- a/i18n/de/docusaurus-plugin-content-docs/current/stacks-academy/bns.md +++ b/i18n/de/docusaurus-plugin-content-docs/current/stacks-academy/bns.md @@ -32,7 +32,7 @@ What kinds of things do we want to be true about names? In BNS, names are global - **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. +- 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: From 90075f30027af24ef4dd681d67d98762b5be34c7 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Thu, 26 Oct 2023 20:07:50 +0200 Subject: [PATCH 1254/1444] New translations authentication.md (Japanese) --- .../current/stacks-academy/authentication.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/stacks-academy/authentication.md b/i18n/ja/docusaurus-plugin-content-docs/current/stacks-academy/authentication.md index 8152a401f9..83c5e57cf7 100644 --- a/i18n/ja/docusaurus-plugin-content-docs/current/stacks-academy/authentication.md +++ b/i18n/ja/docusaurus-plugin-content-docs/current/stacks-academy/authentication.md @@ -18,7 +18,7 @@ The authentication flow with Stacks is similar to the typical client-server flow 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. +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: From 65a62ce228fff004c08dda6edca6ad73b09a3a48 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Thu, 26 Oct 2023 20:07:51 +0200 Subject: [PATCH 1255/1444] New translations bns.md (Japanese) --- .../current/stacks-academy/bns.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/stacks-academy/bns.md b/i18n/ja/docusaurus-plugin-content-docs/current/stacks-academy/bns.md index 6f7bb331ab..9f88fabff4 100644 --- a/i18n/ja/docusaurus-plugin-content-docs/current/stacks-academy/bns.md +++ b/i18n/ja/docusaurus-plugin-content-docs/current/stacks-academy/bns.md @@ -32,7 +32,7 @@ What kinds of things do we want to be true about names? In BNS, names are global - **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. +- 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: From 6d02ea40e77f67fff28459f34414ddd443b1450b Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Thu, 26 Oct 2023 20:07:52 +0200 Subject: [PATCH 1256/1444] New translations authentication.md (Korean) --- .../current/stacks-academy/authentication.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/i18n/ko/docusaurus-plugin-content-docs/current/stacks-academy/authentication.md b/i18n/ko/docusaurus-plugin-content-docs/current/stacks-academy/authentication.md index 8152a401f9..83c5e57cf7 100644 --- a/i18n/ko/docusaurus-plugin-content-docs/current/stacks-academy/authentication.md +++ b/i18n/ko/docusaurus-plugin-content-docs/current/stacks-academy/authentication.md @@ -18,7 +18,7 @@ The authentication flow with Stacks is similar to the typical client-server flow 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. +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: From 861a039f62c6519cccf0b7daaca93d1e0fc7b067 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Thu, 26 Oct 2023 20:07:54 +0200 Subject: [PATCH 1257/1444] New translations bns.md (Korean) --- .../current/stacks-academy/bns.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/i18n/ko/docusaurus-plugin-content-docs/current/stacks-academy/bns.md b/i18n/ko/docusaurus-plugin-content-docs/current/stacks-academy/bns.md index 6f7bb331ab..9f88fabff4 100644 --- a/i18n/ko/docusaurus-plugin-content-docs/current/stacks-academy/bns.md +++ b/i18n/ko/docusaurus-plugin-content-docs/current/stacks-academy/bns.md @@ -32,7 +32,7 @@ What kinds of things do we want to be true about names? In BNS, names are global - **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. +- 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: From 7f95ec047ef38913512e103509df0937bbb29c68 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Thu, 26 Oct 2023 20:07:55 +0200 Subject: [PATCH 1258/1444] New translations authentication.md (Russian) --- .../current/stacks-academy/authentication.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/stacks-academy/authentication.md b/i18n/ru/docusaurus-plugin-content-docs/current/stacks-academy/authentication.md index 8152a401f9..83c5e57cf7 100644 --- a/i18n/ru/docusaurus-plugin-content-docs/current/stacks-academy/authentication.md +++ b/i18n/ru/docusaurus-plugin-content-docs/current/stacks-academy/authentication.md @@ -18,7 +18,7 @@ The authentication flow with Stacks is similar to the typical client-server flow 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. +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: From 9502365b4bbeb74fcbd81f28db930aa323353088 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Thu, 26 Oct 2023 20:07:56 +0200 Subject: [PATCH 1259/1444] New translations bns.md (Russian) --- .../current/stacks-academy/bns.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/stacks-academy/bns.md b/i18n/ru/docusaurus-plugin-content-docs/current/stacks-academy/bns.md index 6f7bb331ab..9f88fabff4 100644 --- a/i18n/ru/docusaurus-plugin-content-docs/current/stacks-academy/bns.md +++ b/i18n/ru/docusaurus-plugin-content-docs/current/stacks-academy/bns.md @@ -32,7 +32,7 @@ What kinds of things do we want to be true about names? In BNS, names are global - **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. +- 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: From 232ddfe77c3487cf99eb458fc60e0e660056495c Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Thu, 26 Oct 2023 20:07:57 +0200 Subject: [PATCH 1260/1444] New translations authentication.md (Turkish) --- .../current/stacks-academy/authentication.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/i18n/tr/docusaurus-plugin-content-docs/current/stacks-academy/authentication.md b/i18n/tr/docusaurus-plugin-content-docs/current/stacks-academy/authentication.md index 8152a401f9..83c5e57cf7 100644 --- a/i18n/tr/docusaurus-plugin-content-docs/current/stacks-academy/authentication.md +++ b/i18n/tr/docusaurus-plugin-content-docs/current/stacks-academy/authentication.md @@ -18,7 +18,7 @@ The authentication flow with Stacks is similar to the typical client-server flow 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. +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: From 821f9f510bfbdcd1649ae6a8675061fe0228f142 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Thu, 26 Oct 2023 20:07:58 +0200 Subject: [PATCH 1261/1444] New translations bns.md (Turkish) --- .../current/stacks-academy/bns.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/i18n/tr/docusaurus-plugin-content-docs/current/stacks-academy/bns.md b/i18n/tr/docusaurus-plugin-content-docs/current/stacks-academy/bns.md index 6f7bb331ab..9f88fabff4 100644 --- a/i18n/tr/docusaurus-plugin-content-docs/current/stacks-academy/bns.md +++ b/i18n/tr/docusaurus-plugin-content-docs/current/stacks-academy/bns.md @@ -32,7 +32,7 @@ What kinds of things do we want to be true about names? In BNS, names are global - **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. +- 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: From b47ce725154eeffdac585211ae77aed69e8dc566 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Thu, 26 Oct 2023 20:07:59 +0200 Subject: [PATCH 1262/1444] New translations authentication.md (Chinese Simplified) --- .../current/stacks-academy/authentication.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/stacks-academy/authentication.md b/i18n/zh/docusaurus-plugin-content-docs/current/stacks-academy/authentication.md index 4dba632620..4683ae5eef 100644 --- a/i18n/zh/docusaurus-plugin-content-docs/current/stacks-academy/authentication.md +++ b/i18n/zh/docusaurus-plugin-content-docs/current/stacks-academy/authentication.md @@ -18,7 +18,7 @@ The authentication flow with Stacks is similar to the typical client-server flow 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. +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: From 4fcb327010d723efd3e3a7c113068da806b76bd4 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Thu, 26 Oct 2023 20:08:00 +0200 Subject: [PATCH 1263/1444] New translations bns.md (Chinese Simplified) --- .../current/stacks-academy/bns.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/stacks-academy/bns.md b/i18n/zh/docusaurus-plugin-content-docs/current/stacks-academy/bns.md index e4dc81662b..b7de38b8a8 100644 --- a/i18n/zh/docusaurus-plugin-content-docs/current/stacks-academy/bns.md +++ b/i18n/zh/docusaurus-plugin-content-docs/current/stacks-academy/bns.md @@ -32,7 +32,7 @@ What kinds of things do we want to be true about names? In BNS, names are global - **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. +- 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 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: From 4c1275ee807b33975610e31edbe062f0e1ee5345 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Thu, 26 Oct 2023 20:08:02 +0200 Subject: [PATCH 1264/1444] New translations authentication.md (Vietnamese) --- .../current/stacks-academy/authentication.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/i18n/vi/docusaurus-plugin-content-docs/current/stacks-academy/authentication.md b/i18n/vi/docusaurus-plugin-content-docs/current/stacks-academy/authentication.md index 02296a19a3..59a8929797 100644 --- a/i18n/vi/docusaurus-plugin-content-docs/current/stacks-academy/authentication.md +++ b/i18n/vi/docusaurus-plugin-content-docs/current/stacks-academy/authentication.md @@ -18,7 +18,7 @@ The authentication flow with Stacks is similar to the typical client-server flow 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. +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: From d69b3afa1da36bed393a60d6c14891664dc08af8 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Thu, 26 Oct 2023 20:08:03 +0200 Subject: [PATCH 1265/1444] New translations bns.md (Vietnamese) --- .../current/stacks-academy/bns.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/i18n/vi/docusaurus-plugin-content-docs/current/stacks-academy/bns.md b/i18n/vi/docusaurus-plugin-content-docs/current/stacks-academy/bns.md index 6f7bb331ab..9f88fabff4 100644 --- a/i18n/vi/docusaurus-plugin-content-docs/current/stacks-academy/bns.md +++ b/i18n/vi/docusaurus-plugin-content-docs/current/stacks-academy/bns.md @@ -32,7 +32,7 @@ What kinds of things do we want to be true about names? In BNS, names are global - **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. +- 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: From 0c514209edb3b9df81050c72774d1903bce99f82 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Thu, 26 Oct 2023 20:08:04 +0200 Subject: [PATCH 1266/1444] New translations authentication.md (Portuguese, Brazilian) --- .../current/stacks-academy/authentication.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/i18n/pt/docusaurus-plugin-content-docs/current/stacks-academy/authentication.md b/i18n/pt/docusaurus-plugin-content-docs/current/stacks-academy/authentication.md index c9a62956c1..b00560f5de 100644 --- a/i18n/pt/docusaurus-plugin-content-docs/current/stacks-academy/authentication.md +++ b/i18n/pt/docusaurus-plugin-content-docs/current/stacks-academy/authentication.md @@ -18,7 +18,7 @@ O fluxo de autenticação com Stacks é semelhante ao fluxo típico do servidor 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. O aplicativo de solicitação envia ao autenticador um token `authRequest`. Assim que um usuário aprova a autenticação, o autenticador responde ao aplicativo com um token `authResponse`. -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. +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: From a1a1a16009f899af976fbf604adc8ba983fe767b Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Thu, 26 Oct 2023 20:08:05 +0200 Subject: [PATCH 1267/1444] New translations bns.md (Portuguese, Brazilian) --- .../current/stacks-academy/bns.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/i18n/pt/docusaurus-plugin-content-docs/current/stacks-academy/bns.md b/i18n/pt/docusaurus-plugin-content-docs/current/stacks-academy/bns.md index 4e656499d3..bd23d43c3e 100644 --- a/i18n/pt/docusaurus-plugin-content-docs/current/stacks-academy/bns.md +++ b/i18n/pt/docusaurus-plugin-content-docs/current/stacks-academy/bns.md @@ -32,7 +32,7 @@ What kinds of things do we want to be true about names? In BNS, names are global - **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. +- 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: From 77bee8357ab19fbf9eac536b72ae735eac88abd3 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Thu, 26 Oct 2023 20:08:06 +0200 Subject: [PATCH 1268/1444] New translations authentication.md (Indonesian) --- .../current/stacks-academy/authentication.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/i18n/id/docusaurus-plugin-content-docs/current/stacks-academy/authentication.md b/i18n/id/docusaurus-plugin-content-docs/current/stacks-academy/authentication.md index 1a03fbdc35..af6dc62b7a 100644 --- a/i18n/id/docusaurus-plugin-content-docs/current/stacks-academy/authentication.md +++ b/i18n/id/docusaurus-plugin-content-docs/current/stacks-academy/authentication.md @@ -18,7 +18,7 @@ Alur autentikasi dengan Stacks mirip dengan alur klien-server biasa yang digunak 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. +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. 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: From d4bc6b07b789586737b939d5ae6b4476817964a3 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Thu, 26 Oct 2023 20:08:07 +0200 Subject: [PATCH 1269/1444] New translations bns.md (Indonesian) --- .../current/stacks-academy/bns.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/i18n/id/docusaurus-plugin-content-docs/current/stacks-academy/bns.md b/i18n/id/docusaurus-plugin-content-docs/current/stacks-academy/bns.md index 8fb80c7bdc..a4ebf76115 100644 --- a/i18n/id/docusaurus-plugin-content-docs/current/stacks-academy/bns.md +++ b/i18n/id/docusaurus-plugin-content-docs/current/stacks-academy/bns.md @@ -32,7 +32,7 @@ Hal seperti apa yang kita inginkan untuk menjadi kenyataan mengenai penamaan? Di - **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. +- Di PGP, nama adalah ID kunci. They are globally unique and cryptographically owned, but not human-readable. 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: From 313af324798d57e7caaed24eecf6bfdbb4cbc002 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Thu, 26 Oct 2023 20:08:08 +0200 Subject: [PATCH 1270/1444] New translations authentication.md (Hindi) --- .../current/stacks-academy/authentication.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/i18n/hi/docusaurus-plugin-content-docs/current/stacks-academy/authentication.md b/i18n/hi/docusaurus-plugin-content-docs/current/stacks-academy/authentication.md index 02296a19a3..59a8929797 100644 --- a/i18n/hi/docusaurus-plugin-content-docs/current/stacks-academy/authentication.md +++ b/i18n/hi/docusaurus-plugin-content-docs/current/stacks-academy/authentication.md @@ -18,7 +18,7 @@ The authentication flow with Stacks is similar to the typical client-server flow 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. +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: From 195331b088e8fa8c3ce9905fa751139dc0a895dc Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Thu, 26 Oct 2023 20:08:09 +0200 Subject: [PATCH 1271/1444] New translations bns.md (Hindi) --- .../current/stacks-academy/bns.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/i18n/hi/docusaurus-plugin-content-docs/current/stacks-academy/bns.md b/i18n/hi/docusaurus-plugin-content-docs/current/stacks-academy/bns.md index 6f7bb331ab..9f88fabff4 100644 --- a/i18n/hi/docusaurus-plugin-content-docs/current/stacks-academy/bns.md +++ b/i18n/hi/docusaurus-plugin-content-docs/current/stacks-academy/bns.md @@ -32,7 +32,7 @@ What kinds of things do we want to be true about names? In BNS, names are global - **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. +- 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: From 76a8c4060496b2a50e1f2b174bd7d299453b2cf0 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Thu, 26 Oct 2023 21:34:37 +0200 Subject: [PATCH 1272/1444] Update source file authentication.md --- docs/stacks-academy/authentication.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/stacks-academy/authentication.md b/docs/stacks-academy/authentication.md index 6768e8ba8b..55b89ee93b 100644 --- a/docs/stacks-academy/authentication.md +++ b/docs/stacks-academy/authentication.md @@ -18,7 +18,7 @@ The authentication flow with Stacks is similar to the typical client-server flow 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. +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: From 04272c55e5761176b1f3362edff91e037dabcafb Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Thu, 26 Oct 2023 21:34:37 +0200 Subject: [PATCH 1273/1444] Update source file bns.md --- docs/stacks-academy/bns.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/stacks-academy/bns.md b/docs/stacks-academy/bns.md index 134e8a6a37..66b21d2640 100644 --- a/docs/stacks-academy/bns.md +++ b/docs/stacks-academy/bns.md @@ -65,8 +65,7 @@ guarantees _two_ of these properties. This limits how useful they can be. 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 +- 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. From 90892a0151832b39abebe998e9190a5c89eeff0f Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Mon, 4 Dec 2023 18:45:24 +0100 Subject: [PATCH 1274/1444] New translations community-tutorials.md (Spanish) --- .../current/tutorials/community-tutorials.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/i18n/es/docusaurus-plugin-content-docs/current/tutorials/community-tutorials.md b/i18n/es/docusaurus-plugin-content-docs/current/tutorials/community-tutorials.md index a4f3d970ca..4f8b39fb4d 100644 --- a/i18n/es/docusaurus-plugin-content-docs/current/tutorials/community-tutorials.md +++ b/i18n/es/docusaurus-plugin-content-docs/current/tutorials/community-tutorials.md @@ -1,17 +1,17 @@ --- -title: Community Tutorials -description: Tutorials created by various people in the Stacks community +title: Tutoriales de la comunidad +description: Tutoriales creados por diversas personas de la comunidad de Stacks --- -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. +Estos tutoriales han sido creados por varios miembros de la comunidad de Stacks. ¿Tienes un tutorial para sugerir? Ver la [guía de contribución](http://localhost:3000/docs/contribute/docs) para enviar un PR con un nuevo tutorial añadido. -## Written Tutorials +## Tutoriales Escritos -- [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) +- [Crear una aplicación de Stacks renderizada en el servidor con Remix](https://micro-stacks.dev/guides/with-remix) +- [Construir una aplicación de Stacks con Next.js](https://micro-stacks.dev/guides/with-nextjs) +- [Creación de un contrato de voto](https://www.clearness.dev/01-voting-clarity-smart-contract/01-getting-started) +- [Construir un NFT con Stacks y Clarity](https://blog.developerdao.com/building-an-nft-with-stacks-and-clarity) +- [Acuñar NFTs con 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) From 1f460c5c3b2c05f6df796d6d2019794243c54925 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Mon, 4 Dec 2023 18:45:26 +0100 Subject: [PATCH 1275/1444] New translations hello-stacks.md (Spanish) --- .../current/tutorials/hello-stacks.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/i18n/es/docusaurus-plugin-content-docs/current/tutorials/hello-stacks.md b/i18n/es/docusaurus-plugin-content-docs/current/tutorials/hello-stacks.md index 080f2b0cdd..017f559a5c 100644 --- a/i18n/es/docusaurus-plugin-content-docs/current/tutorials/hello-stacks.md +++ b/i18n/es/docusaurus-plugin-content-docs/current/tutorials/hello-stacks.md @@ -742,7 +742,7 @@ Prefer a more immersive experience? Clarity Universe is a start-to-finish guide [Enroll in Clarity Universe](https://clarity-lang.org/universe) -### Community Tutorials +### Tutoriales de la comunidad 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. From 24de9eaee494e21bd419f0a9ca3aeb08e6e64899 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Tue, 12 Dec 2023 17:26:10 +0100 Subject: [PATCH 1276/1444] New translations btc-connection.md (French) --- .../current/stacks-academy/btc-connection.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/stacks-academy/btc-connection.md b/i18n/fr/docusaurus-plugin-content-docs/current/stacks-academy/btc-connection.md index a3dd62f9ff..eac3bf9091 100644 --- a/i18n/fr/docusaurus-plugin-content-docs/current/stacks-academy/btc-connection.md +++ b/i18n/fr/docusaurus-plugin-content-docs/current/stacks-academy/btc-connection.md @@ -94,9 +94,9 @@ This image broadly means developers can build sovereign rollups on Bitcoin today #### 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 follow Bitcoin finality with 100% Bitcoin hashpower. 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 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 designers of the Nakamoto release have decided to wait for 150 blocks before Bitcoin finality kicks in; this is mostly done to allow short-term forks to be resolved at the Stacks level. This design also means that most Maximal Extractable Value (MEV) action happens on the Stacks layer side and not on the Bitcoin side. There is always a fear of MEV incentives messing with Bitcoin mining, and the Stacks layer explicitly attracts most MEV activity to happen on the Stacks layer vs. Bitcoin L1 (the assumption here is that most MEV activity will occur within 150 blocks). Changing the variable from 150 to 6 blocks is trivial technically and can be configured as needed. Sovereign rollups effectively use a variable of 0 blocks and work similarly to the Stacks layer for reorg resistance. +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. From a1a9e22a6c8338777ae6bbef51bf508d1123151c Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Tue, 12 Dec 2023 17:26:11 +0100 Subject: [PATCH 1277/1444] New translations btc-connection.md (Spanish) --- .../current/stacks-academy/btc-connection.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/i18n/es/docusaurus-plugin-content-docs/current/stacks-academy/btc-connection.md b/i18n/es/docusaurus-plugin-content-docs/current/stacks-academy/btc-connection.md index a3dd62f9ff..eac3bf9091 100644 --- a/i18n/es/docusaurus-plugin-content-docs/current/stacks-academy/btc-connection.md +++ b/i18n/es/docusaurus-plugin-content-docs/current/stacks-academy/btc-connection.md @@ -94,9 +94,9 @@ This image broadly means developers can build sovereign rollups on Bitcoin today #### 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 follow Bitcoin finality with 100% Bitcoin hashpower. 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 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 designers of the Nakamoto release have decided to wait for 150 blocks before Bitcoin finality kicks in; this is mostly done to allow short-term forks to be resolved at the Stacks level. This design also means that most Maximal Extractable Value (MEV) action happens on the Stacks layer side and not on the Bitcoin side. There is always a fear of MEV incentives messing with Bitcoin mining, and the Stacks layer explicitly attracts most MEV activity to happen on the Stacks layer vs. Bitcoin L1 (the assumption here is that most MEV activity will occur within 150 blocks). Changing the variable from 150 to 6 blocks is trivial technically and can be configured as needed. Sovereign rollups effectively use a variable of 0 blocks and work similarly to the Stacks layer for reorg resistance. +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. From ef095840f530544a0e14a549f8fc29edae6d81b2 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Tue, 12 Dec 2023 17:26:13 +0100 Subject: [PATCH 1278/1444] New translations btc-connection.md (German) --- .../current/stacks-academy/btc-connection.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/i18n/de/docusaurus-plugin-content-docs/current/stacks-academy/btc-connection.md b/i18n/de/docusaurus-plugin-content-docs/current/stacks-academy/btc-connection.md index a3dd62f9ff..eac3bf9091 100644 --- a/i18n/de/docusaurus-plugin-content-docs/current/stacks-academy/btc-connection.md +++ b/i18n/de/docusaurus-plugin-content-docs/current/stacks-academy/btc-connection.md @@ -94,9 +94,9 @@ This image broadly means developers can build sovereign rollups on Bitcoin today #### 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 follow Bitcoin finality with 100% Bitcoin hashpower. 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 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 designers of the Nakamoto release have decided to wait for 150 blocks before Bitcoin finality kicks in; this is mostly done to allow short-term forks to be resolved at the Stacks level. This design also means that most Maximal Extractable Value (MEV) action happens on the Stacks layer side and not on the Bitcoin side. There is always a fear of MEV incentives messing with Bitcoin mining, and the Stacks layer explicitly attracts most MEV activity to happen on the Stacks layer vs. Bitcoin L1 (the assumption here is that most MEV activity will occur within 150 blocks). Changing the variable from 150 to 6 blocks is trivial technically and can be configured as needed. Sovereign rollups effectively use a variable of 0 blocks and work similarly to the Stacks layer for reorg resistance. +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. From 87cdca8374a7519eec2c3d0eb901fc085c743234 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Tue, 12 Dec 2023 17:26:14 +0100 Subject: [PATCH 1279/1444] New translations btc-connection.md (Japanese) --- .../current/stacks-academy/btc-connection.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/stacks-academy/btc-connection.md b/i18n/ja/docusaurus-plugin-content-docs/current/stacks-academy/btc-connection.md index a3dd62f9ff..eac3bf9091 100644 --- a/i18n/ja/docusaurus-plugin-content-docs/current/stacks-academy/btc-connection.md +++ b/i18n/ja/docusaurus-plugin-content-docs/current/stacks-academy/btc-connection.md @@ -94,9 +94,9 @@ This image broadly means developers can build sovereign rollups on Bitcoin today #### 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 follow Bitcoin finality with 100% Bitcoin hashpower. 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 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 designers of the Nakamoto release have decided to wait for 150 blocks before Bitcoin finality kicks in; this is mostly done to allow short-term forks to be resolved at the Stacks level. This design also means that most Maximal Extractable Value (MEV) action happens on the Stacks layer side and not on the Bitcoin side. There is always a fear of MEV incentives messing with Bitcoin mining, and the Stacks layer explicitly attracts most MEV activity to happen on the Stacks layer vs. Bitcoin L1 (the assumption here is that most MEV activity will occur within 150 blocks). Changing the variable from 150 to 6 blocks is trivial technically and can be configured as needed. Sovereign rollups effectively use a variable of 0 blocks and work similarly to the Stacks layer for reorg resistance. +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. From dd95826415a4d0924a0d2c39e1a7436dd98f53a1 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Tue, 12 Dec 2023 17:26:15 +0100 Subject: [PATCH 1280/1444] New translations btc-connection.md (Korean) --- .../current/stacks-academy/btc-connection.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/i18n/ko/docusaurus-plugin-content-docs/current/stacks-academy/btc-connection.md b/i18n/ko/docusaurus-plugin-content-docs/current/stacks-academy/btc-connection.md index a3dd62f9ff..eac3bf9091 100644 --- a/i18n/ko/docusaurus-plugin-content-docs/current/stacks-academy/btc-connection.md +++ b/i18n/ko/docusaurus-plugin-content-docs/current/stacks-academy/btc-connection.md @@ -94,9 +94,9 @@ This image broadly means developers can build sovereign rollups on Bitcoin today #### 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 follow Bitcoin finality with 100% Bitcoin hashpower. 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 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 designers of the Nakamoto release have decided to wait for 150 blocks before Bitcoin finality kicks in; this is mostly done to allow short-term forks to be resolved at the Stacks level. This design also means that most Maximal Extractable Value (MEV) action happens on the Stacks layer side and not on the Bitcoin side. There is always a fear of MEV incentives messing with Bitcoin mining, and the Stacks layer explicitly attracts most MEV activity to happen on the Stacks layer vs. Bitcoin L1 (the assumption here is that most MEV activity will occur within 150 blocks). Changing the variable from 150 to 6 blocks is trivial technically and can be configured as needed. Sovereign rollups effectively use a variable of 0 blocks and work similarly to the Stacks layer for reorg resistance. +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. From 1fd230ad3bc2c6ceb39a44275a6a94b6747eed6a Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Tue, 12 Dec 2023 17:26:16 +0100 Subject: [PATCH 1281/1444] New translations btc-connection.md (Russian) --- .../current/stacks-academy/btc-connection.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/stacks-academy/btc-connection.md b/i18n/ru/docusaurus-plugin-content-docs/current/stacks-academy/btc-connection.md index a3dd62f9ff..eac3bf9091 100644 --- a/i18n/ru/docusaurus-plugin-content-docs/current/stacks-academy/btc-connection.md +++ b/i18n/ru/docusaurus-plugin-content-docs/current/stacks-academy/btc-connection.md @@ -94,9 +94,9 @@ This image broadly means developers can build sovereign rollups on Bitcoin today #### 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 follow Bitcoin finality with 100% Bitcoin hashpower. 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 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 designers of the Nakamoto release have decided to wait for 150 blocks before Bitcoin finality kicks in; this is mostly done to allow short-term forks to be resolved at the Stacks level. This design also means that most Maximal Extractable Value (MEV) action happens on the Stacks layer side and not on the Bitcoin side. There is always a fear of MEV incentives messing with Bitcoin mining, and the Stacks layer explicitly attracts most MEV activity to happen on the Stacks layer vs. Bitcoin L1 (the assumption here is that most MEV activity will occur within 150 blocks). Changing the variable from 150 to 6 blocks is trivial technically and can be configured as needed. Sovereign rollups effectively use a variable of 0 blocks and work similarly to the Stacks layer for reorg resistance. +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. From b55bcbf42e92d63f1ed57e996a3a55c111f85352 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Tue, 12 Dec 2023 17:26:17 +0100 Subject: [PATCH 1282/1444] New translations btc-connection.md (Turkish) --- .../current/stacks-academy/btc-connection.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/i18n/tr/docusaurus-plugin-content-docs/current/stacks-academy/btc-connection.md b/i18n/tr/docusaurus-plugin-content-docs/current/stacks-academy/btc-connection.md index a3dd62f9ff..eac3bf9091 100644 --- a/i18n/tr/docusaurus-plugin-content-docs/current/stacks-academy/btc-connection.md +++ b/i18n/tr/docusaurus-plugin-content-docs/current/stacks-academy/btc-connection.md @@ -94,9 +94,9 @@ This image broadly means developers can build sovereign rollups on Bitcoin today #### 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 follow Bitcoin finality with 100% Bitcoin hashpower. 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 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 designers of the Nakamoto release have decided to wait for 150 blocks before Bitcoin finality kicks in; this is mostly done to allow short-term forks to be resolved at the Stacks level. This design also means that most Maximal Extractable Value (MEV) action happens on the Stacks layer side and not on the Bitcoin side. There is always a fear of MEV incentives messing with Bitcoin mining, and the Stacks layer explicitly attracts most MEV activity to happen on the Stacks layer vs. Bitcoin L1 (the assumption here is that most MEV activity will occur within 150 blocks). Changing the variable from 150 to 6 blocks is trivial technically and can be configured as needed. Sovereign rollups effectively use a variable of 0 blocks and work similarly to the Stacks layer for reorg resistance. +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. From 79071e3ff68e2d634ed2711a7356012bc9a6be23 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Tue, 12 Dec 2023 17:26:18 +0100 Subject: [PATCH 1283/1444] New translations btc-connection.md (Chinese Simplified) --- .../current/stacks-academy/btc-connection.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/stacks-academy/btc-connection.md b/i18n/zh/docusaurus-plugin-content-docs/current/stacks-academy/btc-connection.md index a3dd62f9ff..eac3bf9091 100644 --- a/i18n/zh/docusaurus-plugin-content-docs/current/stacks-academy/btc-connection.md +++ b/i18n/zh/docusaurus-plugin-content-docs/current/stacks-academy/btc-connection.md @@ -94,9 +94,9 @@ This image broadly means developers can build sovereign rollups on Bitcoin today #### 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 follow Bitcoin finality with 100% Bitcoin hashpower. 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 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 designers of the Nakamoto release have decided to wait for 150 blocks before Bitcoin finality kicks in; this is mostly done to allow short-term forks to be resolved at the Stacks level. This design also means that most Maximal Extractable Value (MEV) action happens on the Stacks layer side and not on the Bitcoin side. There is always a fear of MEV incentives messing with Bitcoin mining, and the Stacks layer explicitly attracts most MEV activity to happen on the Stacks layer vs. Bitcoin L1 (the assumption here is that most MEV activity will occur within 150 blocks). Changing the variable from 150 to 6 blocks is trivial technically and can be configured as needed. Sovereign rollups effectively use a variable of 0 blocks and work similarly to the Stacks layer for reorg resistance. +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. From 75d34d0e69be50971363594cba0e8a28abe48ec7 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Tue, 12 Dec 2023 17:26:19 +0100 Subject: [PATCH 1284/1444] New translations btc-connection.md (Vietnamese) --- .../current/stacks-academy/btc-connection.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/i18n/vi/docusaurus-plugin-content-docs/current/stacks-academy/btc-connection.md b/i18n/vi/docusaurus-plugin-content-docs/current/stacks-academy/btc-connection.md index a3dd62f9ff..eac3bf9091 100644 --- a/i18n/vi/docusaurus-plugin-content-docs/current/stacks-academy/btc-connection.md +++ b/i18n/vi/docusaurus-plugin-content-docs/current/stacks-academy/btc-connection.md @@ -94,9 +94,9 @@ This image broadly means developers can build sovereign rollups on Bitcoin today #### 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 follow Bitcoin finality with 100% Bitcoin hashpower. 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 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 designers of the Nakamoto release have decided to wait for 150 blocks before Bitcoin finality kicks in; this is mostly done to allow short-term forks to be resolved at the Stacks level. This design also means that most Maximal Extractable Value (MEV) action happens on the Stacks layer side and not on the Bitcoin side. There is always a fear of MEV incentives messing with Bitcoin mining, and the Stacks layer explicitly attracts most MEV activity to happen on the Stacks layer vs. Bitcoin L1 (the assumption here is that most MEV activity will occur within 150 blocks). Changing the variable from 150 to 6 blocks is trivial technically and can be configured as needed. Sovereign rollups effectively use a variable of 0 blocks and work similarly to the Stacks layer for reorg resistance. +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. From 9c08544660a1ea67cede9054d153f6b8df1b601a Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Tue, 12 Dec 2023 17:26:21 +0100 Subject: [PATCH 1285/1444] New translations btc-connection.md (Portuguese, Brazilian) --- .../current/stacks-academy/btc-connection.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/i18n/pt/docusaurus-plugin-content-docs/current/stacks-academy/btc-connection.md b/i18n/pt/docusaurus-plugin-content-docs/current/stacks-academy/btc-connection.md index a3dd62f9ff..eac3bf9091 100644 --- a/i18n/pt/docusaurus-plugin-content-docs/current/stacks-academy/btc-connection.md +++ b/i18n/pt/docusaurus-plugin-content-docs/current/stacks-academy/btc-connection.md @@ -94,9 +94,9 @@ This image broadly means developers can build sovereign rollups on Bitcoin today #### 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 follow Bitcoin finality with 100% Bitcoin hashpower. 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 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 designers of the Nakamoto release have decided to wait for 150 blocks before Bitcoin finality kicks in; this is mostly done to allow short-term forks to be resolved at the Stacks level. This design also means that most Maximal Extractable Value (MEV) action happens on the Stacks layer side and not on the Bitcoin side. There is always a fear of MEV incentives messing with Bitcoin mining, and the Stacks layer explicitly attracts most MEV activity to happen on the Stacks layer vs. Bitcoin L1 (the assumption here is that most MEV activity will occur within 150 blocks). Changing the variable from 150 to 6 blocks is trivial technically and can be configured as needed. Sovereign rollups effectively use a variable of 0 blocks and work similarly to the Stacks layer for reorg resistance. +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. From 3e7787cbe95834d24d92e411ff1e680189926328 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Tue, 12 Dec 2023 17:26:22 +0100 Subject: [PATCH 1286/1444] New translations btc-connection.md (Indonesian) --- .../current/stacks-academy/btc-connection.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/i18n/id/docusaurus-plugin-content-docs/current/stacks-academy/btc-connection.md b/i18n/id/docusaurus-plugin-content-docs/current/stacks-academy/btc-connection.md index a3dd62f9ff..eac3bf9091 100644 --- a/i18n/id/docusaurus-plugin-content-docs/current/stacks-academy/btc-connection.md +++ b/i18n/id/docusaurus-plugin-content-docs/current/stacks-academy/btc-connection.md @@ -94,9 +94,9 @@ This image broadly means developers can build sovereign rollups on Bitcoin today #### 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 follow Bitcoin finality with 100% Bitcoin hashpower. 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 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 designers of the Nakamoto release have decided to wait for 150 blocks before Bitcoin finality kicks in; this is mostly done to allow short-term forks to be resolved at the Stacks level. This design also means that most Maximal Extractable Value (MEV) action happens on the Stacks layer side and not on the Bitcoin side. There is always a fear of MEV incentives messing with Bitcoin mining, and the Stacks layer explicitly attracts most MEV activity to happen on the Stacks layer vs. Bitcoin L1 (the assumption here is that most MEV activity will occur within 150 blocks). Changing the variable from 150 to 6 blocks is trivial technically and can be configured as needed. Sovereign rollups effectively use a variable of 0 blocks and work similarly to the Stacks layer for reorg resistance. +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. From 920f1fad5b23b6a3c98a0772a4661b1a7e7d4814 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Tue, 12 Dec 2023 17:26:23 +0100 Subject: [PATCH 1287/1444] New translations btc-connection.md (Hindi) --- .../current/stacks-academy/btc-connection.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/i18n/hi/docusaurus-plugin-content-docs/current/stacks-academy/btc-connection.md b/i18n/hi/docusaurus-plugin-content-docs/current/stacks-academy/btc-connection.md index a3dd62f9ff..eac3bf9091 100644 --- a/i18n/hi/docusaurus-plugin-content-docs/current/stacks-academy/btc-connection.md +++ b/i18n/hi/docusaurus-plugin-content-docs/current/stacks-academy/btc-connection.md @@ -94,9 +94,9 @@ This image broadly means developers can build sovereign rollups on Bitcoin today #### 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 follow Bitcoin finality with 100% Bitcoin hashpower. 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 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 designers of the Nakamoto release have decided to wait for 150 blocks before Bitcoin finality kicks in; this is mostly done to allow short-term forks to be resolved at the Stacks level. This design also means that most Maximal Extractable Value (MEV) action happens on the Stacks layer side and not on the Bitcoin side. There is always a fear of MEV incentives messing with Bitcoin mining, and the Stacks layer explicitly attracts most MEV activity to happen on the Stacks layer vs. Bitcoin L1 (the assumption here is that most MEV activity will occur within 150 blocks). Changing the variable from 150 to 6 blocks is trivial technically and can be configured as needed. Sovereign rollups effectively use a variable of 0 blocks and work similarly to the Stacks layer for reorg resistance. +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. From 5ddc6aa147902f03b79c9fa717c6b2a9465b0a35 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Tue, 12 Dec 2023 18:50:06 +0100 Subject: [PATCH 1288/1444] Update source file btc-connection.md --- docs/stacks-academy/btc-connection.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/stacks-academy/btc-connection.md b/docs/stacks-academy/btc-connection.md index 105c15d83d..1fd8b988c3 100644 --- a/docs/stacks-academy/btc-connection.md +++ b/docs/stacks-academy/btc-connection.md @@ -94,9 +94,9 @@ This image broadly means developers can build sovereign rollups on Bitcoin today #### 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 follow Bitcoin finality with 100% Bitcoin hashpower. 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 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 designers of the Nakamoto release have decided to wait for 150 blocks before Bitcoin finality kicks in; this is mostly done to allow short-term forks to be resolved at the Stacks level. This design also means that most Maximal Extractable Value (MEV) action happens on the Stacks layer side and not on the Bitcoin side. There is always a fear of MEV incentives messing with Bitcoin mining, and the Stacks layer explicitly attracts most MEV activity to happen on the Stacks layer vs. Bitcoin L1 (the assumption here is that most MEV activity will occur within 150 blocks). Changing the variable from 150 to 6 blocks is trivial technically and can be configured as needed. Sovereign rollups effectively use a variable of 0 blocks and work similarly to the Stacks layer for reorg resistance. +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. From 562dc4a6530800430684e9e70ca6fc89730d8b63 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Mon, 8 Jan 2024 23:10:55 +0100 Subject: [PATCH 1289/1444] New translations intro.md (French) --- .../docusaurus-plugin-content-docs/current/intro.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/intro.md b/i18n/fr/docusaurus-plugin-content-docs/current/intro.md index 951a0e5824..f284f060c8 100644 --- a/i18n/fr/docusaurus-plugin-content-docs/current/intro.md +++ b/i18n/fr/docusaurus-plugin-content-docs/current/intro.md @@ -15,6 +15,18 @@ These docs serve as: 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. From ff6285fcfad99a362d1ccd7bbe704d4b54d16af1 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Mon, 8 Jan 2024 23:10:56 +0100 Subject: [PATCH 1290/1444] New translations bitcoin-mev-mitigation.md (French) --- .../nakamoto/bitcoin-mev-mitigation.md | 62 +++++++++++++++++++ 1 file changed, 62 insertions(+) create mode 100644 i18n/fr/docusaurus-plugin-content-docs/current/nakamoto/bitcoin-mev-mitigation.md diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/nakamoto/bitcoin-mev-mitigation.md b/i18n/fr/docusaurus-plugin-content-docs/current/nakamoto/bitcoin-mev-mitigation.md new file mode 100644 index 0000000000..46c768ce69 --- /dev/null +++ b/i18n/fr/docusaurus-plugin-content-docs/current/nakamoto/bitcoin-mev-mitigation.md @@ -0,0 +1,62 @@ +--- +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). From 2d74b1b9ec4a790805367765c065b3c604e9fb6f Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Mon, 8 Jan 2024 23:10:57 +0100 Subject: [PATCH 1291/1444] New translations block-production.md (French) --- .../current/nakamoto/block-production.md | 48 +++++++++++++++++++ 1 file changed, 48 insertions(+) create mode 100644 i18n/fr/docusaurus-plugin-content-docs/current/nakamoto/block-production.md diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/nakamoto/block-production.md b/i18n/fr/docusaurus-plugin-content-docs/current/nakamoto/block-production.md new file mode 100644 index 0000000000..2137f2b4b6 --- /dev/null +++ b/i18n/fr/docusaurus-plugin-content-docs/current/nakamoto/block-production.md @@ -0,0 +1,48 @@ +--- +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. From 095f02e9b6c041c7f58b103e3bade0f0caa459dc Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Mon, 8 Jan 2024 23:10:58 +0100 Subject: [PATCH 1292/1444] New translations clarity-wasm.md (French) --- .../current/nakamoto/clarity-wasm.md | 7 +++++++ 1 file changed, 7 insertions(+) create mode 100644 i18n/fr/docusaurus-plugin-content-docs/current/nakamoto/clarity-wasm.md diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/nakamoto/clarity-wasm.md b/i18n/fr/docusaurus-plugin-content-docs/current/nakamoto/clarity-wasm.md new file mode 100644 index 0000000000..ecf28e3e90 --- /dev/null +++ b/i18n/fr/docusaurus-plugin-content-docs/current/nakamoto/clarity-wasm.md @@ -0,0 +1,7 @@ +--- +title: Clarity WASM +description: The new Clarity WASM runtime +sidebar_label: Clarity WASM +sidebar_position: 5 +draft: true +--- From 0d5131836080fe275de44aa9932e75d0b443e1eb Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Mon, 8 Jan 2024 23:10:59 +0100 Subject: [PATCH 1293/1444] New translations index.md (French) --- .../current/nakamoto/index.md | 28 +++++++++++++++++++ 1 file changed, 28 insertions(+) create mode 100644 i18n/fr/docusaurus-plugin-content-docs/current/nakamoto/index.md diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/nakamoto/index.md b/i18n/fr/docusaurus-plugin-content-docs/current/nakamoto/index.md new file mode 100644 index 0000000000..75c7e53007 --- /dev/null +++ b/i18n/fr/docusaurus-plugin-content-docs/current/nakamoto/index.md @@ -0,0 +1,28 @@ +--- +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). From cb94e5fd43f8b00b593786e6f89f46442f55ee6d Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Mon, 8 Jan 2024 23:11:00 +0100 Subject: [PATCH 1294/1444] New translations neon.md (French) --- .../current/nakamoto/neon.md | 32 +++++++++++++++++++ 1 file changed, 32 insertions(+) create mode 100644 i18n/fr/docusaurus-plugin-content-docs/current/nakamoto/neon.md diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/nakamoto/neon.md b/i18n/fr/docusaurus-plugin-content-docs/current/nakamoto/neon.md new file mode 100644 index 0000000000..5305b8eab1 --- /dev/null +++ b/i18n/fr/docusaurus-plugin-content-docs/current/nakamoto/neon.md @@ -0,0 +1,32 @@ +--- +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. From 4efc9d55f4935ee7159e09df2b636be18063be17 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Mon, 8 Jan 2024 23:11:04 +0100 Subject: [PATCH 1295/1444] New translations intro.md (Spanish) --- .../docusaurus-plugin-content-docs/current/intro.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/i18n/es/docusaurus-plugin-content-docs/current/intro.md b/i18n/es/docusaurus-plugin-content-docs/current/intro.md index 68d02b19ba..9ebbf5aab9 100644 --- a/i18n/es/docusaurus-plugin-content-docs/current/intro.md +++ b/i18n/es/docusaurus-plugin-content-docs/current/intro.md @@ -15,6 +15,18 @@ These docs serve as: 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. From b34c5c5361a73c49c0ea2b8792a4083c652c0271 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Mon, 8 Jan 2024 23:11:06 +0100 Subject: [PATCH 1296/1444] New translations bitcoin-mev-mitigation.md (Spanish) --- .../nakamoto/bitcoin-mev-mitigation.md | 62 +++++++++++++++++++ 1 file changed, 62 insertions(+) create mode 100644 i18n/es/docusaurus-plugin-content-docs/current/nakamoto/bitcoin-mev-mitigation.md diff --git a/i18n/es/docusaurus-plugin-content-docs/current/nakamoto/bitcoin-mev-mitigation.md b/i18n/es/docusaurus-plugin-content-docs/current/nakamoto/bitcoin-mev-mitigation.md new file mode 100644 index 0000000000..46c768ce69 --- /dev/null +++ b/i18n/es/docusaurus-plugin-content-docs/current/nakamoto/bitcoin-mev-mitigation.md @@ -0,0 +1,62 @@ +--- +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). From 73978311bca73b4afd636c8e04f54d5129d3f85b Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Mon, 8 Jan 2024 23:11:06 +0100 Subject: [PATCH 1297/1444] New translations block-production.md (Spanish) --- .../current/nakamoto/block-production.md | 48 +++++++++++++++++++ 1 file changed, 48 insertions(+) create mode 100644 i18n/es/docusaurus-plugin-content-docs/current/nakamoto/block-production.md diff --git a/i18n/es/docusaurus-plugin-content-docs/current/nakamoto/block-production.md b/i18n/es/docusaurus-plugin-content-docs/current/nakamoto/block-production.md new file mode 100644 index 0000000000..2137f2b4b6 --- /dev/null +++ b/i18n/es/docusaurus-plugin-content-docs/current/nakamoto/block-production.md @@ -0,0 +1,48 @@ +--- +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. From ac9ac13b2fbbeb7302a81e541102d402f5a6c52b Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Mon, 8 Jan 2024 23:11:07 +0100 Subject: [PATCH 1298/1444] New translations clarity-wasm.md (Spanish) --- .../current/nakamoto/clarity-wasm.md | 7 +++++++ 1 file changed, 7 insertions(+) create mode 100644 i18n/es/docusaurus-plugin-content-docs/current/nakamoto/clarity-wasm.md diff --git a/i18n/es/docusaurus-plugin-content-docs/current/nakamoto/clarity-wasm.md b/i18n/es/docusaurus-plugin-content-docs/current/nakamoto/clarity-wasm.md new file mode 100644 index 0000000000..ecf28e3e90 --- /dev/null +++ b/i18n/es/docusaurus-plugin-content-docs/current/nakamoto/clarity-wasm.md @@ -0,0 +1,7 @@ +--- +title: Clarity WASM +description: The new Clarity WASM runtime +sidebar_label: Clarity WASM +sidebar_position: 5 +draft: true +--- From 6b312e05c34327d764b3fe54faf85c13c529b930 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Mon, 8 Jan 2024 23:11:08 +0100 Subject: [PATCH 1299/1444] New translations index.md (Spanish) --- .../current/nakamoto/index.md | 28 +++++++++++++++++++ 1 file changed, 28 insertions(+) create mode 100644 i18n/es/docusaurus-plugin-content-docs/current/nakamoto/index.md diff --git a/i18n/es/docusaurus-plugin-content-docs/current/nakamoto/index.md b/i18n/es/docusaurus-plugin-content-docs/current/nakamoto/index.md new file mode 100644 index 0000000000..75c7e53007 --- /dev/null +++ b/i18n/es/docusaurus-plugin-content-docs/current/nakamoto/index.md @@ -0,0 +1,28 @@ +--- +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). From 87c74e317ea136d608c00ab2f4c8633329c04907 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Mon, 8 Jan 2024 23:11:09 +0100 Subject: [PATCH 1300/1444] New translations neon.md (Spanish) --- .../current/nakamoto/neon.md | 32 +++++++++++++++++++ 1 file changed, 32 insertions(+) create mode 100644 i18n/es/docusaurus-plugin-content-docs/current/nakamoto/neon.md diff --git a/i18n/es/docusaurus-plugin-content-docs/current/nakamoto/neon.md b/i18n/es/docusaurus-plugin-content-docs/current/nakamoto/neon.md new file mode 100644 index 0000000000..5305b8eab1 --- /dev/null +++ b/i18n/es/docusaurus-plugin-content-docs/current/nakamoto/neon.md @@ -0,0 +1,32 @@ +--- +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. From 96e84455a6839753ecdc1d0d2993cdd19627c28c Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Mon, 8 Jan 2024 23:11:14 +0100 Subject: [PATCH 1301/1444] New translations intro.md (German) --- .../docusaurus-plugin-content-docs/current/intro.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/i18n/de/docusaurus-plugin-content-docs/current/intro.md b/i18n/de/docusaurus-plugin-content-docs/current/intro.md index 951a0e5824..f284f060c8 100644 --- a/i18n/de/docusaurus-plugin-content-docs/current/intro.md +++ b/i18n/de/docusaurus-plugin-content-docs/current/intro.md @@ -15,6 +15,18 @@ These docs serve as: 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. From 75daa9430c4228ee4be3f7221a137d20e30cb43c Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Mon, 8 Jan 2024 23:11:15 +0100 Subject: [PATCH 1302/1444] New translations bitcoin-mev-mitigation.md (German) --- .../nakamoto/bitcoin-mev-mitigation.md | 62 +++++++++++++++++++ 1 file changed, 62 insertions(+) create mode 100644 i18n/de/docusaurus-plugin-content-docs/current/nakamoto/bitcoin-mev-mitigation.md diff --git a/i18n/de/docusaurus-plugin-content-docs/current/nakamoto/bitcoin-mev-mitigation.md b/i18n/de/docusaurus-plugin-content-docs/current/nakamoto/bitcoin-mev-mitigation.md new file mode 100644 index 0000000000..46c768ce69 --- /dev/null +++ b/i18n/de/docusaurus-plugin-content-docs/current/nakamoto/bitcoin-mev-mitigation.md @@ -0,0 +1,62 @@ +--- +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). From c125c5a75a260bb3c0d9c23d317b0ecbbd30b65a Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Mon, 8 Jan 2024 23:11:16 +0100 Subject: [PATCH 1303/1444] New translations block-production.md (German) --- .../current/nakamoto/block-production.md | 48 +++++++++++++++++++ 1 file changed, 48 insertions(+) create mode 100644 i18n/de/docusaurus-plugin-content-docs/current/nakamoto/block-production.md diff --git a/i18n/de/docusaurus-plugin-content-docs/current/nakamoto/block-production.md b/i18n/de/docusaurus-plugin-content-docs/current/nakamoto/block-production.md new file mode 100644 index 0000000000..2137f2b4b6 --- /dev/null +++ b/i18n/de/docusaurus-plugin-content-docs/current/nakamoto/block-production.md @@ -0,0 +1,48 @@ +--- +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. From 30028de242881e23e78828570bc88d74ddf39575 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Mon, 8 Jan 2024 23:11:17 +0100 Subject: [PATCH 1304/1444] New translations clarity-wasm.md (German) --- .../current/nakamoto/clarity-wasm.md | 7 +++++++ 1 file changed, 7 insertions(+) create mode 100644 i18n/de/docusaurus-plugin-content-docs/current/nakamoto/clarity-wasm.md diff --git a/i18n/de/docusaurus-plugin-content-docs/current/nakamoto/clarity-wasm.md b/i18n/de/docusaurus-plugin-content-docs/current/nakamoto/clarity-wasm.md new file mode 100644 index 0000000000..ecf28e3e90 --- /dev/null +++ b/i18n/de/docusaurus-plugin-content-docs/current/nakamoto/clarity-wasm.md @@ -0,0 +1,7 @@ +--- +title: Clarity WASM +description: The new Clarity WASM runtime +sidebar_label: Clarity WASM +sidebar_position: 5 +draft: true +--- From 56b4d1519862153052895c01e86ea7f4ff32070d Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Mon, 8 Jan 2024 23:11:18 +0100 Subject: [PATCH 1305/1444] New translations index.md (German) --- .../current/nakamoto/index.md | 28 +++++++++++++++++++ 1 file changed, 28 insertions(+) create mode 100644 i18n/de/docusaurus-plugin-content-docs/current/nakamoto/index.md diff --git a/i18n/de/docusaurus-plugin-content-docs/current/nakamoto/index.md b/i18n/de/docusaurus-plugin-content-docs/current/nakamoto/index.md new file mode 100644 index 0000000000..75c7e53007 --- /dev/null +++ b/i18n/de/docusaurus-plugin-content-docs/current/nakamoto/index.md @@ -0,0 +1,28 @@ +--- +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). From 1a813f5bfe6a476bac155e9611a885630d30583f Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Mon, 8 Jan 2024 23:11:19 +0100 Subject: [PATCH 1306/1444] New translations neon.md (German) --- .../current/nakamoto/neon.md | 32 +++++++++++++++++++ 1 file changed, 32 insertions(+) create mode 100644 i18n/de/docusaurus-plugin-content-docs/current/nakamoto/neon.md diff --git a/i18n/de/docusaurus-plugin-content-docs/current/nakamoto/neon.md b/i18n/de/docusaurus-plugin-content-docs/current/nakamoto/neon.md new file mode 100644 index 0000000000..5305b8eab1 --- /dev/null +++ b/i18n/de/docusaurus-plugin-content-docs/current/nakamoto/neon.md @@ -0,0 +1,32 @@ +--- +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. From 3a928fd2c82f900a12d52afe89b4cb73879502e4 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Mon, 8 Jan 2024 23:11:23 +0100 Subject: [PATCH 1307/1444] New translations intro.md (Japanese) --- .../docusaurus-plugin-content-docs/current/intro.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/intro.md b/i18n/ja/docusaurus-plugin-content-docs/current/intro.md index 951a0e5824..f284f060c8 100644 --- a/i18n/ja/docusaurus-plugin-content-docs/current/intro.md +++ b/i18n/ja/docusaurus-plugin-content-docs/current/intro.md @@ -15,6 +15,18 @@ These docs serve as: 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. From 6d6492d81e53bdd2a2fa560f1e7324083b03cef1 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Mon, 8 Jan 2024 23:11:24 +0100 Subject: [PATCH 1308/1444] New translations bitcoin-mev-mitigation.md (Japanese) --- .../nakamoto/bitcoin-mev-mitigation.md | 62 +++++++++++++++++++ 1 file changed, 62 insertions(+) create mode 100644 i18n/ja/docusaurus-plugin-content-docs/current/nakamoto/bitcoin-mev-mitigation.md diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/nakamoto/bitcoin-mev-mitigation.md b/i18n/ja/docusaurus-plugin-content-docs/current/nakamoto/bitcoin-mev-mitigation.md new file mode 100644 index 0000000000..46c768ce69 --- /dev/null +++ b/i18n/ja/docusaurus-plugin-content-docs/current/nakamoto/bitcoin-mev-mitigation.md @@ -0,0 +1,62 @@ +--- +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). From 5aadfc4b2b7083a9729ace463be3ff65122ecddb Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Mon, 8 Jan 2024 23:11:25 +0100 Subject: [PATCH 1309/1444] New translations block-production.md (Japanese) --- .../current/nakamoto/block-production.md | 48 +++++++++++++++++++ 1 file changed, 48 insertions(+) create mode 100644 i18n/ja/docusaurus-plugin-content-docs/current/nakamoto/block-production.md diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/nakamoto/block-production.md b/i18n/ja/docusaurus-plugin-content-docs/current/nakamoto/block-production.md new file mode 100644 index 0000000000..2137f2b4b6 --- /dev/null +++ b/i18n/ja/docusaurus-plugin-content-docs/current/nakamoto/block-production.md @@ -0,0 +1,48 @@ +--- +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. From 16be458981a91909b591c266984dae363cd372eb Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Mon, 8 Jan 2024 23:11:26 +0100 Subject: [PATCH 1310/1444] New translations clarity-wasm.md (Japanese) --- .../current/nakamoto/clarity-wasm.md | 7 +++++++ 1 file changed, 7 insertions(+) create mode 100644 i18n/ja/docusaurus-plugin-content-docs/current/nakamoto/clarity-wasm.md diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/nakamoto/clarity-wasm.md b/i18n/ja/docusaurus-plugin-content-docs/current/nakamoto/clarity-wasm.md new file mode 100644 index 0000000000..ecf28e3e90 --- /dev/null +++ b/i18n/ja/docusaurus-plugin-content-docs/current/nakamoto/clarity-wasm.md @@ -0,0 +1,7 @@ +--- +title: Clarity WASM +description: The new Clarity WASM runtime +sidebar_label: Clarity WASM +sidebar_position: 5 +draft: true +--- From 1313c111db2897a7514ec2d762eb1b6ee1563dc6 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Mon, 8 Jan 2024 23:11:27 +0100 Subject: [PATCH 1311/1444] New translations index.md (Japanese) --- .../current/nakamoto/index.md | 28 +++++++++++++++++++ 1 file changed, 28 insertions(+) create mode 100644 i18n/ja/docusaurus-plugin-content-docs/current/nakamoto/index.md diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/nakamoto/index.md b/i18n/ja/docusaurus-plugin-content-docs/current/nakamoto/index.md new file mode 100644 index 0000000000..75c7e53007 --- /dev/null +++ b/i18n/ja/docusaurus-plugin-content-docs/current/nakamoto/index.md @@ -0,0 +1,28 @@ +--- +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). From 339bc469d0d61cb725d1e514a7f1ba2c5fadebaf Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Mon, 8 Jan 2024 23:11:28 +0100 Subject: [PATCH 1312/1444] New translations neon.md (Japanese) --- .../current/nakamoto/neon.md | 32 +++++++++++++++++++ 1 file changed, 32 insertions(+) create mode 100644 i18n/ja/docusaurus-plugin-content-docs/current/nakamoto/neon.md diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/nakamoto/neon.md b/i18n/ja/docusaurus-plugin-content-docs/current/nakamoto/neon.md new file mode 100644 index 0000000000..5305b8eab1 --- /dev/null +++ b/i18n/ja/docusaurus-plugin-content-docs/current/nakamoto/neon.md @@ -0,0 +1,32 @@ +--- +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. From a3f15634e02aebc5483080e6f089eebcc283ee27 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Mon, 8 Jan 2024 23:11:32 +0100 Subject: [PATCH 1313/1444] New translations intro.md (Korean) --- .../docusaurus-plugin-content-docs/current/intro.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/i18n/ko/docusaurus-plugin-content-docs/current/intro.md b/i18n/ko/docusaurus-plugin-content-docs/current/intro.md index 951a0e5824..f284f060c8 100644 --- a/i18n/ko/docusaurus-plugin-content-docs/current/intro.md +++ b/i18n/ko/docusaurus-plugin-content-docs/current/intro.md @@ -15,6 +15,18 @@ These docs serve as: 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. From 518103d3c913939e86eac2ece24f574111b48d6c Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Mon, 8 Jan 2024 23:11:33 +0100 Subject: [PATCH 1314/1444] New translations bitcoin-mev-mitigation.md (Korean) --- .../nakamoto/bitcoin-mev-mitigation.md | 62 +++++++++++++++++++ 1 file changed, 62 insertions(+) create mode 100644 i18n/ko/docusaurus-plugin-content-docs/current/nakamoto/bitcoin-mev-mitigation.md diff --git a/i18n/ko/docusaurus-plugin-content-docs/current/nakamoto/bitcoin-mev-mitigation.md b/i18n/ko/docusaurus-plugin-content-docs/current/nakamoto/bitcoin-mev-mitigation.md new file mode 100644 index 0000000000..46c768ce69 --- /dev/null +++ b/i18n/ko/docusaurus-plugin-content-docs/current/nakamoto/bitcoin-mev-mitigation.md @@ -0,0 +1,62 @@ +--- +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). From 4909edc6d10cfe740fc355149a6bf9d26a1481a5 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Mon, 8 Jan 2024 23:11:34 +0100 Subject: [PATCH 1315/1444] New translations block-production.md (Korean) --- .../current/nakamoto/block-production.md | 48 +++++++++++++++++++ 1 file changed, 48 insertions(+) create mode 100644 i18n/ko/docusaurus-plugin-content-docs/current/nakamoto/block-production.md diff --git a/i18n/ko/docusaurus-plugin-content-docs/current/nakamoto/block-production.md b/i18n/ko/docusaurus-plugin-content-docs/current/nakamoto/block-production.md new file mode 100644 index 0000000000..2137f2b4b6 --- /dev/null +++ b/i18n/ko/docusaurus-plugin-content-docs/current/nakamoto/block-production.md @@ -0,0 +1,48 @@ +--- +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. From 1a83914115ba75d8e58e767fddda839e85620b54 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Mon, 8 Jan 2024 23:11:35 +0100 Subject: [PATCH 1316/1444] New translations clarity-wasm.md (Korean) --- .../current/nakamoto/clarity-wasm.md | 7 +++++++ 1 file changed, 7 insertions(+) create mode 100644 i18n/ko/docusaurus-plugin-content-docs/current/nakamoto/clarity-wasm.md diff --git a/i18n/ko/docusaurus-plugin-content-docs/current/nakamoto/clarity-wasm.md b/i18n/ko/docusaurus-plugin-content-docs/current/nakamoto/clarity-wasm.md new file mode 100644 index 0000000000..ecf28e3e90 --- /dev/null +++ b/i18n/ko/docusaurus-plugin-content-docs/current/nakamoto/clarity-wasm.md @@ -0,0 +1,7 @@ +--- +title: Clarity WASM +description: The new Clarity WASM runtime +sidebar_label: Clarity WASM +sidebar_position: 5 +draft: true +--- From 48291bc9136ee56ddcc927ea04b51561cb328d95 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Mon, 8 Jan 2024 23:11:36 +0100 Subject: [PATCH 1317/1444] New translations index.md (Korean) --- .../current/nakamoto/index.md | 28 +++++++++++++++++++ 1 file changed, 28 insertions(+) create mode 100644 i18n/ko/docusaurus-plugin-content-docs/current/nakamoto/index.md diff --git a/i18n/ko/docusaurus-plugin-content-docs/current/nakamoto/index.md b/i18n/ko/docusaurus-plugin-content-docs/current/nakamoto/index.md new file mode 100644 index 0000000000..75c7e53007 --- /dev/null +++ b/i18n/ko/docusaurus-plugin-content-docs/current/nakamoto/index.md @@ -0,0 +1,28 @@ +--- +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). From 10f69c3ea6298e0606c3b6e6a6f235c7f4e54c61 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Mon, 8 Jan 2024 23:11:37 +0100 Subject: [PATCH 1318/1444] New translations neon.md (Korean) --- .../current/nakamoto/neon.md | 32 +++++++++++++++++++ 1 file changed, 32 insertions(+) create mode 100644 i18n/ko/docusaurus-plugin-content-docs/current/nakamoto/neon.md diff --git a/i18n/ko/docusaurus-plugin-content-docs/current/nakamoto/neon.md b/i18n/ko/docusaurus-plugin-content-docs/current/nakamoto/neon.md new file mode 100644 index 0000000000..5305b8eab1 --- /dev/null +++ b/i18n/ko/docusaurus-plugin-content-docs/current/nakamoto/neon.md @@ -0,0 +1,32 @@ +--- +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. From 1aa902010850c72b5897eace28fe5be91591246f Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Mon, 8 Jan 2024 23:11:42 +0100 Subject: [PATCH 1319/1444] New translations intro.md (Russian) --- .../docusaurus-plugin-content-docs/current/intro.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/intro.md b/i18n/ru/docusaurus-plugin-content-docs/current/intro.md index 951a0e5824..f284f060c8 100644 --- a/i18n/ru/docusaurus-plugin-content-docs/current/intro.md +++ b/i18n/ru/docusaurus-plugin-content-docs/current/intro.md @@ -15,6 +15,18 @@ These docs serve as: 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. From 4cf107e2914f75b821575c3bec27afb6ada09ca1 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Mon, 8 Jan 2024 23:11:43 +0100 Subject: [PATCH 1320/1444] New translations bitcoin-mev-mitigation.md (Russian) --- .../nakamoto/bitcoin-mev-mitigation.md | 62 +++++++++++++++++++ 1 file changed, 62 insertions(+) create mode 100644 i18n/ru/docusaurus-plugin-content-docs/current/nakamoto/bitcoin-mev-mitigation.md diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/nakamoto/bitcoin-mev-mitigation.md b/i18n/ru/docusaurus-plugin-content-docs/current/nakamoto/bitcoin-mev-mitigation.md new file mode 100644 index 0000000000..46c768ce69 --- /dev/null +++ b/i18n/ru/docusaurus-plugin-content-docs/current/nakamoto/bitcoin-mev-mitigation.md @@ -0,0 +1,62 @@ +--- +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). From 8619f638253f547c1f547dc8fa2ac23bdceac438 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Mon, 8 Jan 2024 23:11:44 +0100 Subject: [PATCH 1321/1444] New translations block-production.md (Russian) --- .../current/nakamoto/block-production.md | 48 +++++++++++++++++++ 1 file changed, 48 insertions(+) create mode 100644 i18n/ru/docusaurus-plugin-content-docs/current/nakamoto/block-production.md diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/nakamoto/block-production.md b/i18n/ru/docusaurus-plugin-content-docs/current/nakamoto/block-production.md new file mode 100644 index 0000000000..2137f2b4b6 --- /dev/null +++ b/i18n/ru/docusaurus-plugin-content-docs/current/nakamoto/block-production.md @@ -0,0 +1,48 @@ +--- +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. From 09c0ad418798ef72e08ba682bbcfc2a9c7a9f090 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Mon, 8 Jan 2024 23:11:45 +0100 Subject: [PATCH 1322/1444] New translations clarity-wasm.md (Russian) --- .../current/nakamoto/clarity-wasm.md | 7 +++++++ 1 file changed, 7 insertions(+) create mode 100644 i18n/ru/docusaurus-plugin-content-docs/current/nakamoto/clarity-wasm.md diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/nakamoto/clarity-wasm.md b/i18n/ru/docusaurus-plugin-content-docs/current/nakamoto/clarity-wasm.md new file mode 100644 index 0000000000..ecf28e3e90 --- /dev/null +++ b/i18n/ru/docusaurus-plugin-content-docs/current/nakamoto/clarity-wasm.md @@ -0,0 +1,7 @@ +--- +title: Clarity WASM +description: The new Clarity WASM runtime +sidebar_label: Clarity WASM +sidebar_position: 5 +draft: true +--- From c276669f241328419f80c3089692c2d72677474f Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Mon, 8 Jan 2024 23:11:45 +0100 Subject: [PATCH 1323/1444] New translations index.md (Russian) --- .../current/nakamoto/index.md | 28 +++++++++++++++++++ 1 file changed, 28 insertions(+) create mode 100644 i18n/ru/docusaurus-plugin-content-docs/current/nakamoto/index.md diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/nakamoto/index.md b/i18n/ru/docusaurus-plugin-content-docs/current/nakamoto/index.md new file mode 100644 index 0000000000..75c7e53007 --- /dev/null +++ b/i18n/ru/docusaurus-plugin-content-docs/current/nakamoto/index.md @@ -0,0 +1,28 @@ +--- +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). From 119d4aad19ed3022220de4aff976b6fab017bc29 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Mon, 8 Jan 2024 23:11:46 +0100 Subject: [PATCH 1324/1444] New translations neon.md (Russian) --- .../current/nakamoto/neon.md | 32 +++++++++++++++++++ 1 file changed, 32 insertions(+) create mode 100644 i18n/ru/docusaurus-plugin-content-docs/current/nakamoto/neon.md diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/nakamoto/neon.md b/i18n/ru/docusaurus-plugin-content-docs/current/nakamoto/neon.md new file mode 100644 index 0000000000..5305b8eab1 --- /dev/null +++ b/i18n/ru/docusaurus-plugin-content-docs/current/nakamoto/neon.md @@ -0,0 +1,32 @@ +--- +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. From 324f90c4b9234db6185a3974a3a9d79ef9646d85 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Mon, 8 Jan 2024 23:11:51 +0100 Subject: [PATCH 1325/1444] New translations intro.md (Turkish) --- .../docusaurus-plugin-content-docs/current/intro.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/i18n/tr/docusaurus-plugin-content-docs/current/intro.md b/i18n/tr/docusaurus-plugin-content-docs/current/intro.md index 951a0e5824..f284f060c8 100644 --- a/i18n/tr/docusaurus-plugin-content-docs/current/intro.md +++ b/i18n/tr/docusaurus-plugin-content-docs/current/intro.md @@ -15,6 +15,18 @@ These docs serve as: 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. From 65ee9b03da65e870b4c1ac80c482edb5ebfa77cf Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Mon, 8 Jan 2024 23:11:52 +0100 Subject: [PATCH 1326/1444] New translations bitcoin-mev-mitigation.md (Turkish) --- .../nakamoto/bitcoin-mev-mitigation.md | 62 +++++++++++++++++++ 1 file changed, 62 insertions(+) create mode 100644 i18n/tr/docusaurus-plugin-content-docs/current/nakamoto/bitcoin-mev-mitigation.md diff --git a/i18n/tr/docusaurus-plugin-content-docs/current/nakamoto/bitcoin-mev-mitigation.md b/i18n/tr/docusaurus-plugin-content-docs/current/nakamoto/bitcoin-mev-mitigation.md new file mode 100644 index 0000000000..46c768ce69 --- /dev/null +++ b/i18n/tr/docusaurus-plugin-content-docs/current/nakamoto/bitcoin-mev-mitigation.md @@ -0,0 +1,62 @@ +--- +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). From 1aceab5e325a8a049a0ebeddd6ea5c1384edabf3 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Mon, 8 Jan 2024 23:11:53 +0100 Subject: [PATCH 1327/1444] New translations block-production.md (Turkish) --- .../current/nakamoto/block-production.md | 48 +++++++++++++++++++ 1 file changed, 48 insertions(+) create mode 100644 i18n/tr/docusaurus-plugin-content-docs/current/nakamoto/block-production.md diff --git a/i18n/tr/docusaurus-plugin-content-docs/current/nakamoto/block-production.md b/i18n/tr/docusaurus-plugin-content-docs/current/nakamoto/block-production.md new file mode 100644 index 0000000000..2137f2b4b6 --- /dev/null +++ b/i18n/tr/docusaurus-plugin-content-docs/current/nakamoto/block-production.md @@ -0,0 +1,48 @@ +--- +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. From e704eab71ca0c7fa7d3d47f90816344bbcc3f502 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Mon, 8 Jan 2024 23:11:54 +0100 Subject: [PATCH 1328/1444] New translations clarity-wasm.md (Turkish) --- .../current/nakamoto/clarity-wasm.md | 7 +++++++ 1 file changed, 7 insertions(+) create mode 100644 i18n/tr/docusaurus-plugin-content-docs/current/nakamoto/clarity-wasm.md diff --git a/i18n/tr/docusaurus-plugin-content-docs/current/nakamoto/clarity-wasm.md b/i18n/tr/docusaurus-plugin-content-docs/current/nakamoto/clarity-wasm.md new file mode 100644 index 0000000000..ecf28e3e90 --- /dev/null +++ b/i18n/tr/docusaurus-plugin-content-docs/current/nakamoto/clarity-wasm.md @@ -0,0 +1,7 @@ +--- +title: Clarity WASM +description: The new Clarity WASM runtime +sidebar_label: Clarity WASM +sidebar_position: 5 +draft: true +--- From 687c85086851e60c3b1ae47e8829f7961a06e1b1 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Mon, 8 Jan 2024 23:11:55 +0100 Subject: [PATCH 1329/1444] New translations index.md (Turkish) --- .../current/nakamoto/index.md | 28 +++++++++++++++++++ 1 file changed, 28 insertions(+) create mode 100644 i18n/tr/docusaurus-plugin-content-docs/current/nakamoto/index.md diff --git a/i18n/tr/docusaurus-plugin-content-docs/current/nakamoto/index.md b/i18n/tr/docusaurus-plugin-content-docs/current/nakamoto/index.md new file mode 100644 index 0000000000..75c7e53007 --- /dev/null +++ b/i18n/tr/docusaurus-plugin-content-docs/current/nakamoto/index.md @@ -0,0 +1,28 @@ +--- +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). From 6433084ae093d9a47e6b0ec3da1ff9f8b1169ebe Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Mon, 8 Jan 2024 23:11:56 +0100 Subject: [PATCH 1330/1444] New translations neon.md (Turkish) --- .../current/nakamoto/neon.md | 32 +++++++++++++++++++ 1 file changed, 32 insertions(+) create mode 100644 i18n/tr/docusaurus-plugin-content-docs/current/nakamoto/neon.md diff --git a/i18n/tr/docusaurus-plugin-content-docs/current/nakamoto/neon.md b/i18n/tr/docusaurus-plugin-content-docs/current/nakamoto/neon.md new file mode 100644 index 0000000000..5305b8eab1 --- /dev/null +++ b/i18n/tr/docusaurus-plugin-content-docs/current/nakamoto/neon.md @@ -0,0 +1,32 @@ +--- +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. From ded1e09b5a91e6ebb1a0969311a712e8ca986fdf Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Mon, 8 Jan 2024 23:12:01 +0100 Subject: [PATCH 1331/1444] New translations intro.md (Chinese Simplified) --- .../docusaurus-plugin-content-docs/current/intro.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/intro.md b/i18n/zh/docusaurus-plugin-content-docs/current/intro.md index 951a0e5824..f284f060c8 100644 --- a/i18n/zh/docusaurus-plugin-content-docs/current/intro.md +++ b/i18n/zh/docusaurus-plugin-content-docs/current/intro.md @@ -15,6 +15,18 @@ These docs serve as: 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. From eec597a1c9cc7bf6f00c7ee751c7123103bf185e Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Mon, 8 Jan 2024 23:12:02 +0100 Subject: [PATCH 1332/1444] New translations bitcoin-mev-mitigation.md (Chinese Simplified) --- .../nakamoto/bitcoin-mev-mitigation.md | 62 +++++++++++++++++++ 1 file changed, 62 insertions(+) create mode 100644 i18n/zh/docusaurus-plugin-content-docs/current/nakamoto/bitcoin-mev-mitigation.md diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/nakamoto/bitcoin-mev-mitigation.md b/i18n/zh/docusaurus-plugin-content-docs/current/nakamoto/bitcoin-mev-mitigation.md new file mode 100644 index 0000000000..46c768ce69 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/current/nakamoto/bitcoin-mev-mitigation.md @@ -0,0 +1,62 @@ +--- +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). From e55dd5f44f947f6fe89da97a31a1fe92dd35ed32 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Mon, 8 Jan 2024 23:12:03 +0100 Subject: [PATCH 1333/1444] New translations block-production.md (Chinese Simplified) --- .../current/nakamoto/block-production.md | 48 +++++++++++++++++++ 1 file changed, 48 insertions(+) create mode 100644 i18n/zh/docusaurus-plugin-content-docs/current/nakamoto/block-production.md diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/nakamoto/block-production.md b/i18n/zh/docusaurus-plugin-content-docs/current/nakamoto/block-production.md new file mode 100644 index 0000000000..2137f2b4b6 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/current/nakamoto/block-production.md @@ -0,0 +1,48 @@ +--- +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. From 2eabddc387924c78b18705a75f1697da3d456fc7 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Mon, 8 Jan 2024 23:12:04 +0100 Subject: [PATCH 1334/1444] New translations clarity-wasm.md (Chinese Simplified) --- .../current/nakamoto/clarity-wasm.md | 7 +++++++ 1 file changed, 7 insertions(+) create mode 100644 i18n/zh/docusaurus-plugin-content-docs/current/nakamoto/clarity-wasm.md diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/nakamoto/clarity-wasm.md b/i18n/zh/docusaurus-plugin-content-docs/current/nakamoto/clarity-wasm.md new file mode 100644 index 0000000000..ecf28e3e90 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/current/nakamoto/clarity-wasm.md @@ -0,0 +1,7 @@ +--- +title: Clarity WASM +description: The new Clarity WASM runtime +sidebar_label: Clarity WASM +sidebar_position: 5 +draft: true +--- From 54a677c3ceff8f4a97c66e567baa9ddfa92e06d4 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Mon, 8 Jan 2024 23:12:05 +0100 Subject: [PATCH 1335/1444] New translations index.md (Chinese Simplified) --- .../current/nakamoto/index.md | 28 +++++++++++++++++++ 1 file changed, 28 insertions(+) create mode 100644 i18n/zh/docusaurus-plugin-content-docs/current/nakamoto/index.md diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/nakamoto/index.md b/i18n/zh/docusaurus-plugin-content-docs/current/nakamoto/index.md new file mode 100644 index 0000000000..75c7e53007 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/current/nakamoto/index.md @@ -0,0 +1,28 @@ +--- +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). From fcbc350efcc146f93835b8c69bd1aaddef98abb0 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Mon, 8 Jan 2024 23:12:06 +0100 Subject: [PATCH 1336/1444] New translations neon.md (Chinese Simplified) --- .../current/nakamoto/neon.md | 32 +++++++++++++++++++ 1 file changed, 32 insertions(+) create mode 100644 i18n/zh/docusaurus-plugin-content-docs/current/nakamoto/neon.md diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/nakamoto/neon.md b/i18n/zh/docusaurus-plugin-content-docs/current/nakamoto/neon.md new file mode 100644 index 0000000000..5305b8eab1 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/current/nakamoto/neon.md @@ -0,0 +1,32 @@ +--- +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. From d7f8331f6cc74b78aef8f928d5bb9cb27a7f8a16 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Mon, 8 Jan 2024 23:12:10 +0100 Subject: [PATCH 1337/1444] New translations intro.md (Vietnamese) --- .../docusaurus-plugin-content-docs/current/intro.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/i18n/vi/docusaurus-plugin-content-docs/current/intro.md b/i18n/vi/docusaurus-plugin-content-docs/current/intro.md index 951a0e5824..f284f060c8 100644 --- a/i18n/vi/docusaurus-plugin-content-docs/current/intro.md +++ b/i18n/vi/docusaurus-plugin-content-docs/current/intro.md @@ -15,6 +15,18 @@ These docs serve as: 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. From 48cd2d464f67e4305e540db129dc30a79db170e3 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Mon, 8 Jan 2024 23:12:11 +0100 Subject: [PATCH 1338/1444] New translations bitcoin-mev-mitigation.md (Vietnamese) --- .../nakamoto/bitcoin-mev-mitigation.md | 62 +++++++++++++++++++ 1 file changed, 62 insertions(+) create mode 100644 i18n/vi/docusaurus-plugin-content-docs/current/nakamoto/bitcoin-mev-mitigation.md diff --git a/i18n/vi/docusaurus-plugin-content-docs/current/nakamoto/bitcoin-mev-mitigation.md b/i18n/vi/docusaurus-plugin-content-docs/current/nakamoto/bitcoin-mev-mitigation.md new file mode 100644 index 0000000000..46c768ce69 --- /dev/null +++ b/i18n/vi/docusaurus-plugin-content-docs/current/nakamoto/bitcoin-mev-mitigation.md @@ -0,0 +1,62 @@ +--- +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). From c428b24cd071d567e2c6fc6633e65af0377d0a7d Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Mon, 8 Jan 2024 23:12:12 +0100 Subject: [PATCH 1339/1444] New translations block-production.md (Vietnamese) --- .../current/nakamoto/block-production.md | 48 +++++++++++++++++++ 1 file changed, 48 insertions(+) create mode 100644 i18n/vi/docusaurus-plugin-content-docs/current/nakamoto/block-production.md diff --git a/i18n/vi/docusaurus-plugin-content-docs/current/nakamoto/block-production.md b/i18n/vi/docusaurus-plugin-content-docs/current/nakamoto/block-production.md new file mode 100644 index 0000000000..2137f2b4b6 --- /dev/null +++ b/i18n/vi/docusaurus-plugin-content-docs/current/nakamoto/block-production.md @@ -0,0 +1,48 @@ +--- +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. From c92bef21f3c02ab5e37b7ee8fd7dc51f355fb72c Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Mon, 8 Jan 2024 23:12:13 +0100 Subject: [PATCH 1340/1444] New translations clarity-wasm.md (Vietnamese) --- .../current/nakamoto/clarity-wasm.md | 7 +++++++ 1 file changed, 7 insertions(+) create mode 100644 i18n/vi/docusaurus-plugin-content-docs/current/nakamoto/clarity-wasm.md diff --git a/i18n/vi/docusaurus-plugin-content-docs/current/nakamoto/clarity-wasm.md b/i18n/vi/docusaurus-plugin-content-docs/current/nakamoto/clarity-wasm.md new file mode 100644 index 0000000000..ecf28e3e90 --- /dev/null +++ b/i18n/vi/docusaurus-plugin-content-docs/current/nakamoto/clarity-wasm.md @@ -0,0 +1,7 @@ +--- +title: Clarity WASM +description: The new Clarity WASM runtime +sidebar_label: Clarity WASM +sidebar_position: 5 +draft: true +--- From a614e70258b64df7960c919f8b01f954fed7e9e8 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Mon, 8 Jan 2024 23:12:14 +0100 Subject: [PATCH 1341/1444] New translations index.md (Vietnamese) --- .../current/nakamoto/index.md | 28 +++++++++++++++++++ 1 file changed, 28 insertions(+) create mode 100644 i18n/vi/docusaurus-plugin-content-docs/current/nakamoto/index.md diff --git a/i18n/vi/docusaurus-plugin-content-docs/current/nakamoto/index.md b/i18n/vi/docusaurus-plugin-content-docs/current/nakamoto/index.md new file mode 100644 index 0000000000..75c7e53007 --- /dev/null +++ b/i18n/vi/docusaurus-plugin-content-docs/current/nakamoto/index.md @@ -0,0 +1,28 @@ +--- +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). From 4754f1d9b0b7fcbcb7b2a18332a37e5d570a0e69 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Mon, 8 Jan 2024 23:12:15 +0100 Subject: [PATCH 1342/1444] New translations neon.md (Vietnamese) --- .../current/nakamoto/neon.md | 32 +++++++++++++++++++ 1 file changed, 32 insertions(+) create mode 100644 i18n/vi/docusaurus-plugin-content-docs/current/nakamoto/neon.md diff --git a/i18n/vi/docusaurus-plugin-content-docs/current/nakamoto/neon.md b/i18n/vi/docusaurus-plugin-content-docs/current/nakamoto/neon.md new file mode 100644 index 0000000000..5305b8eab1 --- /dev/null +++ b/i18n/vi/docusaurus-plugin-content-docs/current/nakamoto/neon.md @@ -0,0 +1,32 @@ +--- +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. From 1b34ed7f69334975e3878c3a1b3500c8a0284a84 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Mon, 8 Jan 2024 23:12:19 +0100 Subject: [PATCH 1343/1444] New translations intro.md (Portuguese, Brazilian) --- .../docusaurus-plugin-content-docs/current/intro.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/i18n/pt/docusaurus-plugin-content-docs/current/intro.md b/i18n/pt/docusaurus-plugin-content-docs/current/intro.md index 951a0e5824..f284f060c8 100644 --- a/i18n/pt/docusaurus-plugin-content-docs/current/intro.md +++ b/i18n/pt/docusaurus-plugin-content-docs/current/intro.md @@ -15,6 +15,18 @@ These docs serve as: 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. From f8291ef581dc720e02018b24642d5488207f8e80 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Mon, 8 Jan 2024 23:12:21 +0100 Subject: [PATCH 1344/1444] New translations bitcoin-mev-mitigation.md (Portuguese, Brazilian) --- .../nakamoto/bitcoin-mev-mitigation.md | 62 +++++++++++++++++++ 1 file changed, 62 insertions(+) create mode 100644 i18n/pt/docusaurus-plugin-content-docs/current/nakamoto/bitcoin-mev-mitigation.md diff --git a/i18n/pt/docusaurus-plugin-content-docs/current/nakamoto/bitcoin-mev-mitigation.md b/i18n/pt/docusaurus-plugin-content-docs/current/nakamoto/bitcoin-mev-mitigation.md new file mode 100644 index 0000000000..46c768ce69 --- /dev/null +++ b/i18n/pt/docusaurus-plugin-content-docs/current/nakamoto/bitcoin-mev-mitigation.md @@ -0,0 +1,62 @@ +--- +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). From a22cdf07d5d915037826adc55d8fa6dd74de71a1 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Mon, 8 Jan 2024 23:12:22 +0100 Subject: [PATCH 1345/1444] New translations block-production.md (Portuguese, Brazilian) --- .../current/nakamoto/block-production.md | 48 +++++++++++++++++++ 1 file changed, 48 insertions(+) create mode 100644 i18n/pt/docusaurus-plugin-content-docs/current/nakamoto/block-production.md diff --git a/i18n/pt/docusaurus-plugin-content-docs/current/nakamoto/block-production.md b/i18n/pt/docusaurus-plugin-content-docs/current/nakamoto/block-production.md new file mode 100644 index 0000000000..2137f2b4b6 --- /dev/null +++ b/i18n/pt/docusaurus-plugin-content-docs/current/nakamoto/block-production.md @@ -0,0 +1,48 @@ +--- +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. From 41492eca41acc223d5051c2c0aebfbedbedaee27 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Mon, 8 Jan 2024 23:12:22 +0100 Subject: [PATCH 1346/1444] New translations clarity-wasm.md (Portuguese, Brazilian) --- .../current/nakamoto/clarity-wasm.md | 7 +++++++ 1 file changed, 7 insertions(+) create mode 100644 i18n/pt/docusaurus-plugin-content-docs/current/nakamoto/clarity-wasm.md diff --git a/i18n/pt/docusaurus-plugin-content-docs/current/nakamoto/clarity-wasm.md b/i18n/pt/docusaurus-plugin-content-docs/current/nakamoto/clarity-wasm.md new file mode 100644 index 0000000000..ecf28e3e90 --- /dev/null +++ b/i18n/pt/docusaurus-plugin-content-docs/current/nakamoto/clarity-wasm.md @@ -0,0 +1,7 @@ +--- +title: Clarity WASM +description: The new Clarity WASM runtime +sidebar_label: Clarity WASM +sidebar_position: 5 +draft: true +--- From 2e124530f629ba58ecee56e00f00fa93ef099aa7 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Mon, 8 Jan 2024 23:12:24 +0100 Subject: [PATCH 1347/1444] New translations index.md (Portuguese, Brazilian) --- .../current/nakamoto/index.md | 28 +++++++++++++++++++ 1 file changed, 28 insertions(+) create mode 100644 i18n/pt/docusaurus-plugin-content-docs/current/nakamoto/index.md diff --git a/i18n/pt/docusaurus-plugin-content-docs/current/nakamoto/index.md b/i18n/pt/docusaurus-plugin-content-docs/current/nakamoto/index.md new file mode 100644 index 0000000000..75c7e53007 --- /dev/null +++ b/i18n/pt/docusaurus-plugin-content-docs/current/nakamoto/index.md @@ -0,0 +1,28 @@ +--- +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). From ff307c612995b275ba6dddd680d22d64ef14277a Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Mon, 8 Jan 2024 23:12:25 +0100 Subject: [PATCH 1348/1444] New translations neon.md (Portuguese, Brazilian) --- .../current/nakamoto/neon.md | 32 +++++++++++++++++++ 1 file changed, 32 insertions(+) create mode 100644 i18n/pt/docusaurus-plugin-content-docs/current/nakamoto/neon.md diff --git a/i18n/pt/docusaurus-plugin-content-docs/current/nakamoto/neon.md b/i18n/pt/docusaurus-plugin-content-docs/current/nakamoto/neon.md new file mode 100644 index 0000000000..5305b8eab1 --- /dev/null +++ b/i18n/pt/docusaurus-plugin-content-docs/current/nakamoto/neon.md @@ -0,0 +1,32 @@ +--- +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. From 21a370d2b21a2b177b2ea5f38c729ff00b408ff2 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Mon, 8 Jan 2024 23:12:29 +0100 Subject: [PATCH 1349/1444] New translations intro.md (Indonesian) --- .../docusaurus-plugin-content-docs/current/intro.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/i18n/id/docusaurus-plugin-content-docs/current/intro.md b/i18n/id/docusaurus-plugin-content-docs/current/intro.md index 34767dc88a..4736c2006d 100644 --- a/i18n/id/docusaurus-plugin-content-docs/current/intro.md +++ b/i18n/id/docusaurus-plugin-content-docs/current/intro.md @@ -15,6 +15,18 @@ These docs serve as: 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. From ebc8418108b3c29d5bc191b408f786be118b17a8 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Mon, 8 Jan 2024 23:12:30 +0100 Subject: [PATCH 1350/1444] New translations bitcoin-mev-mitigation.md (Indonesian) --- .../nakamoto/bitcoin-mev-mitigation.md | 62 +++++++++++++++++++ 1 file changed, 62 insertions(+) create mode 100644 i18n/id/docusaurus-plugin-content-docs/current/nakamoto/bitcoin-mev-mitigation.md diff --git a/i18n/id/docusaurus-plugin-content-docs/current/nakamoto/bitcoin-mev-mitigation.md b/i18n/id/docusaurus-plugin-content-docs/current/nakamoto/bitcoin-mev-mitigation.md new file mode 100644 index 0000000000..46c768ce69 --- /dev/null +++ b/i18n/id/docusaurus-plugin-content-docs/current/nakamoto/bitcoin-mev-mitigation.md @@ -0,0 +1,62 @@ +--- +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). From 785cccefbf06b631dadccd7a4786997c243ab9fc Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Mon, 8 Jan 2024 23:12:31 +0100 Subject: [PATCH 1351/1444] New translations block-production.md (Indonesian) --- .../current/nakamoto/block-production.md | 48 +++++++++++++++++++ 1 file changed, 48 insertions(+) create mode 100644 i18n/id/docusaurus-plugin-content-docs/current/nakamoto/block-production.md diff --git a/i18n/id/docusaurus-plugin-content-docs/current/nakamoto/block-production.md b/i18n/id/docusaurus-plugin-content-docs/current/nakamoto/block-production.md new file mode 100644 index 0000000000..2137f2b4b6 --- /dev/null +++ b/i18n/id/docusaurus-plugin-content-docs/current/nakamoto/block-production.md @@ -0,0 +1,48 @@ +--- +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. From ba5962c63dd1d80d225c5b3ad0eb0b85880de293 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Mon, 8 Jan 2024 23:12:32 +0100 Subject: [PATCH 1352/1444] New translations clarity-wasm.md (Indonesian) --- .../current/nakamoto/clarity-wasm.md | 7 +++++++ 1 file changed, 7 insertions(+) create mode 100644 i18n/id/docusaurus-plugin-content-docs/current/nakamoto/clarity-wasm.md diff --git a/i18n/id/docusaurus-plugin-content-docs/current/nakamoto/clarity-wasm.md b/i18n/id/docusaurus-plugin-content-docs/current/nakamoto/clarity-wasm.md new file mode 100644 index 0000000000..ecf28e3e90 --- /dev/null +++ b/i18n/id/docusaurus-plugin-content-docs/current/nakamoto/clarity-wasm.md @@ -0,0 +1,7 @@ +--- +title: Clarity WASM +description: The new Clarity WASM runtime +sidebar_label: Clarity WASM +sidebar_position: 5 +draft: true +--- From ba293ca42cb204b464673e0d0bb24b0e6647e636 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Mon, 8 Jan 2024 23:12:33 +0100 Subject: [PATCH 1353/1444] New translations index.md (Indonesian) --- .../current/nakamoto/index.md | 28 +++++++++++++++++++ 1 file changed, 28 insertions(+) create mode 100644 i18n/id/docusaurus-plugin-content-docs/current/nakamoto/index.md diff --git a/i18n/id/docusaurus-plugin-content-docs/current/nakamoto/index.md b/i18n/id/docusaurus-plugin-content-docs/current/nakamoto/index.md new file mode 100644 index 0000000000..75c7e53007 --- /dev/null +++ b/i18n/id/docusaurus-plugin-content-docs/current/nakamoto/index.md @@ -0,0 +1,28 @@ +--- +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). From 21d8a9ef01ffdec703a22419561100ce880fca44 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Mon, 8 Jan 2024 23:12:34 +0100 Subject: [PATCH 1354/1444] New translations neon.md (Indonesian) --- .../current/nakamoto/neon.md | 32 +++++++++++++++++++ 1 file changed, 32 insertions(+) create mode 100644 i18n/id/docusaurus-plugin-content-docs/current/nakamoto/neon.md diff --git a/i18n/id/docusaurus-plugin-content-docs/current/nakamoto/neon.md b/i18n/id/docusaurus-plugin-content-docs/current/nakamoto/neon.md new file mode 100644 index 0000000000..5305b8eab1 --- /dev/null +++ b/i18n/id/docusaurus-plugin-content-docs/current/nakamoto/neon.md @@ -0,0 +1,32 @@ +--- +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. From 46736d05ae311229a6884cd493df19fd567adc27 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Mon, 8 Jan 2024 23:12:38 +0100 Subject: [PATCH 1355/1444] New translations intro.md (Hindi) --- .../docusaurus-plugin-content-docs/current/intro.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/i18n/hi/docusaurus-plugin-content-docs/current/intro.md b/i18n/hi/docusaurus-plugin-content-docs/current/intro.md index 951a0e5824..f284f060c8 100644 --- a/i18n/hi/docusaurus-plugin-content-docs/current/intro.md +++ b/i18n/hi/docusaurus-plugin-content-docs/current/intro.md @@ -15,6 +15,18 @@ These docs serve as: 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. From bec5e28d959ac448315905da63b04cb5d370d193 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Mon, 8 Jan 2024 23:12:39 +0100 Subject: [PATCH 1356/1444] New translations bitcoin-mev-mitigation.md (Hindi) --- .../nakamoto/bitcoin-mev-mitigation.md | 62 +++++++++++++++++++ 1 file changed, 62 insertions(+) create mode 100644 i18n/hi/docusaurus-plugin-content-docs/current/nakamoto/bitcoin-mev-mitigation.md diff --git a/i18n/hi/docusaurus-plugin-content-docs/current/nakamoto/bitcoin-mev-mitigation.md b/i18n/hi/docusaurus-plugin-content-docs/current/nakamoto/bitcoin-mev-mitigation.md new file mode 100644 index 0000000000..46c768ce69 --- /dev/null +++ b/i18n/hi/docusaurus-plugin-content-docs/current/nakamoto/bitcoin-mev-mitigation.md @@ -0,0 +1,62 @@ +--- +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). From 4d964dd330fa2b202a8ac5bae652a91d83abdd47 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Mon, 8 Jan 2024 23:12:40 +0100 Subject: [PATCH 1357/1444] New translations block-production.md (Hindi) --- .../current/nakamoto/block-production.md | 48 +++++++++++++++++++ 1 file changed, 48 insertions(+) create mode 100644 i18n/hi/docusaurus-plugin-content-docs/current/nakamoto/block-production.md diff --git a/i18n/hi/docusaurus-plugin-content-docs/current/nakamoto/block-production.md b/i18n/hi/docusaurus-plugin-content-docs/current/nakamoto/block-production.md new file mode 100644 index 0000000000..2137f2b4b6 --- /dev/null +++ b/i18n/hi/docusaurus-plugin-content-docs/current/nakamoto/block-production.md @@ -0,0 +1,48 @@ +--- +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. From e391202ea70089ea8d54b6e9f2f28efb2a6ee074 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Mon, 8 Jan 2024 23:12:41 +0100 Subject: [PATCH 1358/1444] New translations clarity-wasm.md (Hindi) --- .../current/nakamoto/clarity-wasm.md | 7 +++++++ 1 file changed, 7 insertions(+) create mode 100644 i18n/hi/docusaurus-plugin-content-docs/current/nakamoto/clarity-wasm.md diff --git a/i18n/hi/docusaurus-plugin-content-docs/current/nakamoto/clarity-wasm.md b/i18n/hi/docusaurus-plugin-content-docs/current/nakamoto/clarity-wasm.md new file mode 100644 index 0000000000..ecf28e3e90 --- /dev/null +++ b/i18n/hi/docusaurus-plugin-content-docs/current/nakamoto/clarity-wasm.md @@ -0,0 +1,7 @@ +--- +title: Clarity WASM +description: The new Clarity WASM runtime +sidebar_label: Clarity WASM +sidebar_position: 5 +draft: true +--- From ba8a4790f60894345c0b7fbf55aaa355e7aedf37 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Mon, 8 Jan 2024 23:12:42 +0100 Subject: [PATCH 1359/1444] New translations index.md (Hindi) --- .../current/nakamoto/index.md | 28 +++++++++++++++++++ 1 file changed, 28 insertions(+) create mode 100644 i18n/hi/docusaurus-plugin-content-docs/current/nakamoto/index.md diff --git a/i18n/hi/docusaurus-plugin-content-docs/current/nakamoto/index.md b/i18n/hi/docusaurus-plugin-content-docs/current/nakamoto/index.md new file mode 100644 index 0000000000..75c7e53007 --- /dev/null +++ b/i18n/hi/docusaurus-plugin-content-docs/current/nakamoto/index.md @@ -0,0 +1,28 @@ +--- +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). From c009a5c91713306f9d35742fe789fc204822295c Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Mon, 8 Jan 2024 23:12:43 +0100 Subject: [PATCH 1360/1444] New translations neon.md (Hindi) --- .../current/nakamoto/neon.md | 32 +++++++++++++++++++ 1 file changed, 32 insertions(+) create mode 100644 i18n/hi/docusaurus-plugin-content-docs/current/nakamoto/neon.md diff --git a/i18n/hi/docusaurus-plugin-content-docs/current/nakamoto/neon.md b/i18n/hi/docusaurus-plugin-content-docs/current/nakamoto/neon.md new file mode 100644 index 0000000000..5305b8eab1 --- /dev/null +++ b/i18n/hi/docusaurus-plugin-content-docs/current/nakamoto/neon.md @@ -0,0 +1,32 @@ +--- +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. From f81881181053322b8eb9c953b62695c3fc0a875a Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Tue, 9 Jan 2024 00:10:24 +0100 Subject: [PATCH 1361/1444] Update source file intro.md --- docs/intro.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/docs/intro.md b/docs/intro.md index 951a0e5824..f284f060c8 100644 --- a/docs/intro.md +++ b/docs/intro.md @@ -15,6 +15,18 @@ These docs serve as: 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. From b8ea7b93b858ed03ba8374897c4724b61d831be1 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Tue, 9 Jan 2024 00:10:24 +0100 Subject: [PATCH 1362/1444] Update source file bitcoin-mev-mitigation.md --- docs/nakamoto/bitcoin-mev-mitigation.md | 62 +++++++++++++++++++++++++ 1 file changed, 62 insertions(+) create mode 100644 docs/nakamoto/bitcoin-mev-mitigation.md diff --git a/docs/nakamoto/bitcoin-mev-mitigation.md b/docs/nakamoto/bitcoin-mev-mitigation.md new file mode 100644 index 0000000000..46c768ce69 --- /dev/null +++ b/docs/nakamoto/bitcoin-mev-mitigation.md @@ -0,0 +1,62 @@ +--- +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). From 5e6517bde9227cb7d70c855aea354d63baf8fc4b Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Tue, 9 Jan 2024 00:10:25 +0100 Subject: [PATCH 1363/1444] Update source file block-production.md --- docs/nakamoto/block-production.md | 48 +++++++++++++++++++++++++++++++ 1 file changed, 48 insertions(+) create mode 100644 docs/nakamoto/block-production.md diff --git a/docs/nakamoto/block-production.md b/docs/nakamoto/block-production.md new file mode 100644 index 0000000000..2137f2b4b6 --- /dev/null +++ b/docs/nakamoto/block-production.md @@ -0,0 +1,48 @@ +--- +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. From 3581575be199afd1d042590ba24475e1438a1e80 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Tue, 9 Jan 2024 00:10:25 +0100 Subject: [PATCH 1364/1444] Update source file clarity-wasm.md --- docs/nakamoto/clarity-wasm.md | 7 +++++++ 1 file changed, 7 insertions(+) create mode 100644 docs/nakamoto/clarity-wasm.md diff --git a/docs/nakamoto/clarity-wasm.md b/docs/nakamoto/clarity-wasm.md new file mode 100644 index 0000000000..ecf28e3e90 --- /dev/null +++ b/docs/nakamoto/clarity-wasm.md @@ -0,0 +1,7 @@ +--- +title: Clarity WASM +description: The new Clarity WASM runtime +sidebar_label: Clarity WASM +sidebar_position: 5 +draft: true +--- From 24825ac2212ae022e5640f61c0e92a6925167c3b Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Tue, 9 Jan 2024 00:10:26 +0100 Subject: [PATCH 1365/1444] Update source file index.md --- docs/nakamoto/index.md | 28 ++++++++++++++++++++++++++++ 1 file changed, 28 insertions(+) create mode 100644 docs/nakamoto/index.md diff --git a/docs/nakamoto/index.md b/docs/nakamoto/index.md new file mode 100644 index 0000000000..979febfe7c --- /dev/null +++ b/docs/nakamoto/index.md @@ -0,0 +1,28 @@ +--- +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). From d5dbbbaf1cd82cf7315a354b9ba6dcf1f2bb94df Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Tue, 9 Jan 2024 00:10:26 +0100 Subject: [PATCH 1366/1444] Update source file neon.md --- docs/nakamoto/neon.md | 32 ++++++++++++++++++++++++++++++++ 1 file changed, 32 insertions(+) create mode 100644 docs/nakamoto/neon.md diff --git a/docs/nakamoto/neon.md b/docs/nakamoto/neon.md new file mode 100644 index 0000000000..ece2bc3372 --- /dev/null +++ b/docs/nakamoto/neon.md @@ -0,0 +1,32 @@ +--- +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. From 5207e17073718f70409f05f764dab892c8f8191b Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Thu, 25 Jan 2024 19:33:51 +0100 Subject: [PATCH 1367/1444] New translations stacking.md (French) --- .../current/stacks-academy/stacking.md | 10 ++++------ 1 file changed, 4 insertions(+), 6 deletions(-) diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/stacks-academy/stacking.md b/i18n/fr/docusaurus-plugin-content-docs/current/stacks-academy/stacking.md index a530bca651..a6f9b9ac96 100644 --- a/i18n/fr/docusaurus-plugin-content-docs/current/stacks-academy/stacking.md +++ b/i18n/fr/docusaurus-plugin-content-docs/current/stacks-academy/stacking.md @@ -85,7 +85,7 @@ Stacks (STX) token holders don't automatically receive stacking rewards. Instead - 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) +- 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. @@ -109,11 +109,9 @@ Stacking is a built-in capability of PoX and occurs through a set of actions on ## 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. ::: +:::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. From 55fc137765db85843ce39c3ee643b8305ef5ea11 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Thu, 25 Jan 2024 19:33:52 +0100 Subject: [PATCH 1368/1444] New translations technical-specs.md (French) --- .../current/stacks-academy/technical-specs.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/stacks-academy/technical-specs.md b/i18n/fr/docusaurus-plugin-content-docs/current/stacks-academy/technical-specs.md index 695f849e1a..6f9fe1599e 100644 --- a/i18n/fr/docusaurus-plugin-content-docs/current/stacks-academy/technical-specs.md +++ b/i18n/fr/docusaurus-plugin-content-docs/current/stacks-academy/technical-specs.md @@ -40,7 +40,7 @@ sidebar_position: 13 - 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. +- All 4 address types are supported: Legacy, SegWit, Native SegWit, and Taproot - Further reading: [Stacking](stacking) ## Accounts and Addresses From 7d1e471a20f52fc20ffde35fe001b8d9b3b61df1 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Thu, 25 Jan 2024 19:33:53 +0100 Subject: [PATCH 1369/1444] New translations stacking-contract.md (French) --- .../current/clarity/noteworthy-contracts/stacking-contract.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/stacking-contract.md b/i18n/fr/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/stacking-contract.md index c0027256cd..6a204159d3 100644 --- a/i18n/fr/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/stacking-contract.md +++ b/i18n/fr/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/stacking-contract.md @@ -145,7 +145,7 @@ 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 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. From 310a34c9baf5fbb7597f9dc94ce3414fc7f27969 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Thu, 25 Jan 2024 19:33:54 +0100 Subject: [PATCH 1370/1444] New translations stacking.md (Spanish) --- .../current/stacks-academy/stacking.md | 10 ++++------ 1 file changed, 4 insertions(+), 6 deletions(-) diff --git a/i18n/es/docusaurus-plugin-content-docs/current/stacks-academy/stacking.md b/i18n/es/docusaurus-plugin-content-docs/current/stacks-academy/stacking.md index 99723c1638..180ca9b909 100644 --- a/i18n/es/docusaurus-plugin-content-docs/current/stacks-academy/stacking.md +++ b/i18n/es/docusaurus-plugin-content-docs/current/stacks-academy/stacking.md @@ -85,7 +85,7 @@ Los poseedores de tokens Stacks (STX) no reciben automáticamente recompensas de - 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) +- Provide a supported Bitcoin address to receive rewards (p2pkh, p2sh, SegWit, or Taproot) 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. @@ -109,11 +109,9 @@ El Stacking es una capacidad integrada de PoX y se produce a través de un conju ## 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. ::: +:::note +Currently, all 4 address types are supported: Legacy, SegWit, Native SegWit, and Taproot. +::: 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. From 9be3206aaf1591c3fad76acd38d1a8f3e62d3e86 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Thu, 25 Jan 2024 19:33:55 +0100 Subject: [PATCH 1371/1444] New translations technical-specs.md (Spanish) --- .../current/stacks-academy/technical-specs.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/i18n/es/docusaurus-plugin-content-docs/current/stacks-academy/technical-specs.md b/i18n/es/docusaurus-plugin-content-docs/current/stacks-academy/technical-specs.md index a955bd3359..b589123173 100644 --- a/i18n/es/docusaurus-plugin-content-docs/current/stacks-academy/technical-specs.md +++ b/i18n/es/docusaurus-plugin-content-docs/current/stacks-academy/technical-specs.md @@ -40,7 +40,7 @@ sidebar_position: 13 - 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. +- All 4 address types are supported: Legacy, SegWit, Native SegWit, and Taproot - Further reading: [Stacking](stacking) ## Cuentas y direcciones From 22280141491dd6b83f39d4163c9f1f4391c7fa39 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Thu, 25 Jan 2024 19:33:56 +0100 Subject: [PATCH 1372/1444] New translations stacking-contract.md (Spanish) --- .../current/clarity/noteworthy-contracts/stacking-contract.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/i18n/es/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/stacking-contract.md b/i18n/es/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/stacking-contract.md index 13443bf2b2..6781a74896 100644 --- a/i18n/es/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/stacking-contract.md +++ b/i18n/es/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/stacking-contract.md @@ -145,7 +145,7 @@ 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 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. From d6e0fb76abe8cdc0999f3deca3986d0ed4e17d21 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Thu, 25 Jan 2024 19:33:57 +0100 Subject: [PATCH 1373/1444] New translations stacking.md (German) --- .../current/stacks-academy/stacking.md | 10 ++++------ 1 file changed, 4 insertions(+), 6 deletions(-) diff --git a/i18n/de/docusaurus-plugin-content-docs/current/stacks-academy/stacking.md b/i18n/de/docusaurus-plugin-content-docs/current/stacks-academy/stacking.md index a530bca651..a6f9b9ac96 100644 --- a/i18n/de/docusaurus-plugin-content-docs/current/stacks-academy/stacking.md +++ b/i18n/de/docusaurus-plugin-content-docs/current/stacks-academy/stacking.md @@ -85,7 +85,7 @@ Stacks (STX) token holders don't automatically receive stacking rewards. Instead - 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) +- 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. @@ -109,11 +109,9 @@ Stacking is a built-in capability of PoX and occurs through a set of actions on ## 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. ::: +:::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. From be83b77f91d0de979fa738c9da34a0d5d90d8a3e Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Thu, 25 Jan 2024 19:33:58 +0100 Subject: [PATCH 1374/1444] New translations technical-specs.md (German) --- .../current/stacks-academy/technical-specs.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/i18n/de/docusaurus-plugin-content-docs/current/stacks-academy/technical-specs.md b/i18n/de/docusaurus-plugin-content-docs/current/stacks-academy/technical-specs.md index 695f849e1a..6f9fe1599e 100644 --- a/i18n/de/docusaurus-plugin-content-docs/current/stacks-academy/technical-specs.md +++ b/i18n/de/docusaurus-plugin-content-docs/current/stacks-academy/technical-specs.md @@ -40,7 +40,7 @@ sidebar_position: 13 - 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. +- All 4 address types are supported: Legacy, SegWit, Native SegWit, and Taproot - Further reading: [Stacking](stacking) ## Accounts and Addresses From 5b490bbf2e56888451a838f3c524f0e10182ccb2 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Thu, 25 Jan 2024 19:33:59 +0100 Subject: [PATCH 1375/1444] New translations stacking-contract.md (German) --- .../current/clarity/noteworthy-contracts/stacking-contract.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/i18n/de/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/stacking-contract.md b/i18n/de/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/stacking-contract.md index c0027256cd..6a204159d3 100644 --- a/i18n/de/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/stacking-contract.md +++ b/i18n/de/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/stacking-contract.md @@ -145,7 +145,7 @@ 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 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. From b106f537f94029d4f66879ed021a8802a79efc58 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Thu, 25 Jan 2024 19:34:00 +0100 Subject: [PATCH 1376/1444] New translations stacking.md (Japanese) --- .../current/stacks-academy/stacking.md | 10 ++++------ 1 file changed, 4 insertions(+), 6 deletions(-) diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/stacks-academy/stacking.md b/i18n/ja/docusaurus-plugin-content-docs/current/stacks-academy/stacking.md index a530bca651..a6f9b9ac96 100644 --- a/i18n/ja/docusaurus-plugin-content-docs/current/stacks-academy/stacking.md +++ b/i18n/ja/docusaurus-plugin-content-docs/current/stacks-academy/stacking.md @@ -85,7 +85,7 @@ Stacks (STX) token holders don't automatically receive stacking rewards. Instead - 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) +- 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. @@ -109,11 +109,9 @@ Stacking is a built-in capability of PoX and occurs through a set of actions on ## 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. ::: +:::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. From 3daf9b4f44a19be92165e2aba76116a36a14e8c9 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Thu, 25 Jan 2024 19:34:01 +0100 Subject: [PATCH 1377/1444] New translations technical-specs.md (Japanese) --- .../current/stacks-academy/technical-specs.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/stacks-academy/technical-specs.md b/i18n/ja/docusaurus-plugin-content-docs/current/stacks-academy/technical-specs.md index 695f849e1a..6f9fe1599e 100644 --- a/i18n/ja/docusaurus-plugin-content-docs/current/stacks-academy/technical-specs.md +++ b/i18n/ja/docusaurus-plugin-content-docs/current/stacks-academy/technical-specs.md @@ -40,7 +40,7 @@ sidebar_position: 13 - 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. +- All 4 address types are supported: Legacy, SegWit, Native SegWit, and Taproot - Further reading: [Stacking](stacking) ## Accounts and Addresses From bdafd6ad91ef622d162b45e6295912cd20c6b815 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Thu, 25 Jan 2024 19:34:03 +0100 Subject: [PATCH 1378/1444] New translations stacking-contract.md (Japanese) --- .../current/clarity/noteworthy-contracts/stacking-contract.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/stacking-contract.md b/i18n/ja/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/stacking-contract.md index c0027256cd..6a204159d3 100644 --- a/i18n/ja/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/stacking-contract.md +++ b/i18n/ja/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/stacking-contract.md @@ -145,7 +145,7 @@ 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 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. From 6c81baeb89666b71bde02ecd03c3fefdf580b2d0 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Thu, 25 Jan 2024 19:34:04 +0100 Subject: [PATCH 1379/1444] New translations stacking.md (Korean) --- .../current/stacks-academy/stacking.md | 10 ++++------ 1 file changed, 4 insertions(+), 6 deletions(-) diff --git a/i18n/ko/docusaurus-plugin-content-docs/current/stacks-academy/stacking.md b/i18n/ko/docusaurus-plugin-content-docs/current/stacks-academy/stacking.md index a530bca651..a6f9b9ac96 100644 --- a/i18n/ko/docusaurus-plugin-content-docs/current/stacks-academy/stacking.md +++ b/i18n/ko/docusaurus-plugin-content-docs/current/stacks-academy/stacking.md @@ -85,7 +85,7 @@ Stacks (STX) token holders don't automatically receive stacking rewards. Instead - 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) +- 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. @@ -109,11 +109,9 @@ Stacking is a built-in capability of PoX and occurs through a set of actions on ## 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. ::: +:::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. From 46351cac21c1c6d56770c16751673cc961c7139d Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Thu, 25 Jan 2024 19:34:05 +0100 Subject: [PATCH 1380/1444] New translations technical-specs.md (Korean) --- .../current/stacks-academy/technical-specs.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/i18n/ko/docusaurus-plugin-content-docs/current/stacks-academy/technical-specs.md b/i18n/ko/docusaurus-plugin-content-docs/current/stacks-academy/technical-specs.md index 695f849e1a..6f9fe1599e 100644 --- a/i18n/ko/docusaurus-plugin-content-docs/current/stacks-academy/technical-specs.md +++ b/i18n/ko/docusaurus-plugin-content-docs/current/stacks-academy/technical-specs.md @@ -40,7 +40,7 @@ sidebar_position: 13 - 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. +- All 4 address types are supported: Legacy, SegWit, Native SegWit, and Taproot - Further reading: [Stacking](stacking) ## Accounts and Addresses From 948efadc45bcccc62af30d7994608d50035f9d39 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Thu, 25 Jan 2024 19:34:06 +0100 Subject: [PATCH 1381/1444] New translations stacking-contract.md (Korean) --- .../current/clarity/noteworthy-contracts/stacking-contract.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/i18n/ko/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/stacking-contract.md b/i18n/ko/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/stacking-contract.md index c0027256cd..6a204159d3 100644 --- a/i18n/ko/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/stacking-contract.md +++ b/i18n/ko/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/stacking-contract.md @@ -145,7 +145,7 @@ 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 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. From ac99d812c734a4d16b82f47d6331370eb99c3b21 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Thu, 25 Jan 2024 19:34:07 +0100 Subject: [PATCH 1382/1444] New translations stacking.md (Russian) --- .../current/stacks-academy/stacking.md | 10 ++++------ 1 file changed, 4 insertions(+), 6 deletions(-) diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/stacks-academy/stacking.md b/i18n/ru/docusaurus-plugin-content-docs/current/stacks-academy/stacking.md index a530bca651..a6f9b9ac96 100644 --- a/i18n/ru/docusaurus-plugin-content-docs/current/stacks-academy/stacking.md +++ b/i18n/ru/docusaurus-plugin-content-docs/current/stacks-academy/stacking.md @@ -85,7 +85,7 @@ Stacks (STX) token holders don't automatically receive stacking rewards. Instead - 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) +- 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. @@ -109,11 +109,9 @@ Stacking is a built-in capability of PoX and occurs through a set of actions on ## 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. ::: +:::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. From daadb7d5bdc1b2e83ff8e781dbb1db7d63179b7a Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Thu, 25 Jan 2024 19:34:08 +0100 Subject: [PATCH 1383/1444] New translations technical-specs.md (Russian) --- .../current/stacks-academy/technical-specs.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/stacks-academy/technical-specs.md b/i18n/ru/docusaurus-plugin-content-docs/current/stacks-academy/technical-specs.md index 695f849e1a..6f9fe1599e 100644 --- a/i18n/ru/docusaurus-plugin-content-docs/current/stacks-academy/technical-specs.md +++ b/i18n/ru/docusaurus-plugin-content-docs/current/stacks-academy/technical-specs.md @@ -40,7 +40,7 @@ sidebar_position: 13 - 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. +- All 4 address types are supported: Legacy, SegWit, Native SegWit, and Taproot - Further reading: [Stacking](stacking) ## Accounts and Addresses From f5df459b4454d2cd673db9088d9201515680899d Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Thu, 25 Jan 2024 19:34:09 +0100 Subject: [PATCH 1384/1444] New translations stacking-contract.md (Russian) --- .../current/clarity/noteworthy-contracts/stacking-contract.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/stacking-contract.md b/i18n/ru/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/stacking-contract.md index c0027256cd..6a204159d3 100644 --- a/i18n/ru/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/stacking-contract.md +++ b/i18n/ru/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/stacking-contract.md @@ -145,7 +145,7 @@ 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 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. From 29ffacf6fae095c093cc1ce56a49a1c78894d9be Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Thu, 25 Jan 2024 19:34:11 +0100 Subject: [PATCH 1385/1444] New translations stacking.md (Turkish) --- .../current/stacks-academy/stacking.md | 10 ++++------ 1 file changed, 4 insertions(+), 6 deletions(-) diff --git a/i18n/tr/docusaurus-plugin-content-docs/current/stacks-academy/stacking.md b/i18n/tr/docusaurus-plugin-content-docs/current/stacks-academy/stacking.md index a530bca651..a6f9b9ac96 100644 --- a/i18n/tr/docusaurus-plugin-content-docs/current/stacks-academy/stacking.md +++ b/i18n/tr/docusaurus-plugin-content-docs/current/stacks-academy/stacking.md @@ -85,7 +85,7 @@ Stacks (STX) token holders don't automatically receive stacking rewards. Instead - 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) +- 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. @@ -109,11 +109,9 @@ Stacking is a built-in capability of PoX and occurs through a set of actions on ## 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. ::: +:::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. From c3bdaf4224a701cdb258e5ad32e34749f2c9db9c Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Thu, 25 Jan 2024 19:34:12 +0100 Subject: [PATCH 1386/1444] New translations technical-specs.md (Turkish) --- .../current/stacks-academy/technical-specs.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/i18n/tr/docusaurus-plugin-content-docs/current/stacks-academy/technical-specs.md b/i18n/tr/docusaurus-plugin-content-docs/current/stacks-academy/technical-specs.md index 695f849e1a..6f9fe1599e 100644 --- a/i18n/tr/docusaurus-plugin-content-docs/current/stacks-academy/technical-specs.md +++ b/i18n/tr/docusaurus-plugin-content-docs/current/stacks-academy/technical-specs.md @@ -40,7 +40,7 @@ sidebar_position: 13 - 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. +- All 4 address types are supported: Legacy, SegWit, Native SegWit, and Taproot - Further reading: [Stacking](stacking) ## Accounts and Addresses From 9b2f54ec06b97fc3982995c0a50b8ff70a4fa28f Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Thu, 25 Jan 2024 19:34:13 +0100 Subject: [PATCH 1387/1444] New translations stacking-contract.md (Turkish) --- .../current/clarity/noteworthy-contracts/stacking-contract.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/i18n/tr/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/stacking-contract.md b/i18n/tr/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/stacking-contract.md index c0027256cd..6a204159d3 100644 --- a/i18n/tr/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/stacking-contract.md +++ b/i18n/tr/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/stacking-contract.md @@ -145,7 +145,7 @@ 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 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. From 69c46d8846094b47f7f38176ddb000e54994100e Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Thu, 25 Jan 2024 19:34:14 +0100 Subject: [PATCH 1388/1444] New translations stacking.md (Chinese Simplified) --- .../current/stacks-academy/stacking.md | 10 ++++------ 1 file changed, 4 insertions(+), 6 deletions(-) diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/stacks-academy/stacking.md b/i18n/zh/docusaurus-plugin-content-docs/current/stacks-academy/stacking.md index b76d072814..9ed9c667fc 100644 --- a/i18n/zh/docusaurus-plugin-content-docs/current/stacks-academy/stacking.md +++ b/i18n/zh/docusaurus-plugin-content-docs/current/stacks-academy/stacking.md @@ -85,7 +85,7 @@ Stacks (STX) token holders don't automatically receive stacking rewards. Instead - 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) +- 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. 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. @@ -109,11 +109,9 @@ Stacking is a built-in capability of PoX and occurs through a set of actions on ## 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. ::: +:::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. 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. From 25e4a0759ed6133300d7b79630de3730f00eb71e Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Thu, 25 Jan 2024 19:34:15 +0100 Subject: [PATCH 1389/1444] New translations technical-specs.md (Chinese Simplified) --- .../current/stacks-academy/technical-specs.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/stacks-academy/technical-specs.md b/i18n/zh/docusaurus-plugin-content-docs/current/stacks-academy/technical-specs.md index 3ecf4936a0..2f0acfd26c 100644 --- a/i18n/zh/docusaurus-plugin-content-docs/current/stacks-academy/technical-specs.md +++ b/i18n/zh/docusaurus-plugin-content-docs/current/stacks-academy/technical-specs.md @@ -40,7 +40,7 @@ sidebar_position: 13 - 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. +- All 4 address types are supported: Legacy, SegWit, Native SegWit, and Taproot - Further reading: [Stacking](stacking) ## Accounts and Addresses From f72ca8cd51d9cde25aa7c82d0ed52e98eae6a6be Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Thu, 25 Jan 2024 19:34:16 +0100 Subject: [PATCH 1390/1444] New translations stacking-contract.md (Chinese Simplified) --- .../current/clarity/noteworthy-contracts/stacking-contract.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/stacking-contract.md b/i18n/zh/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/stacking-contract.md index c0027256cd..6a204159d3 100644 --- a/i18n/zh/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/stacking-contract.md +++ b/i18n/zh/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/stacking-contract.md @@ -145,7 +145,7 @@ 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 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. From 356c6d1cc6099e95794c4e9779f1920ceb235311 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Thu, 25 Jan 2024 19:34:17 +0100 Subject: [PATCH 1391/1444] New translations stacking.md (Vietnamese) --- .../current/stacks-academy/stacking.md | 10 ++++------ 1 file changed, 4 insertions(+), 6 deletions(-) diff --git a/i18n/vi/docusaurus-plugin-content-docs/current/stacks-academy/stacking.md b/i18n/vi/docusaurus-plugin-content-docs/current/stacks-academy/stacking.md index a530bca651..a6f9b9ac96 100644 --- a/i18n/vi/docusaurus-plugin-content-docs/current/stacks-academy/stacking.md +++ b/i18n/vi/docusaurus-plugin-content-docs/current/stacks-academy/stacking.md @@ -85,7 +85,7 @@ Stacks (STX) token holders don't automatically receive stacking rewards. Instead - 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) +- 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. @@ -109,11 +109,9 @@ Stacking is a built-in capability of PoX and occurs through a set of actions on ## 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. ::: +:::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. From ab88fb8340d9bdf85a58b352e77deda2ecbbbfeb Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Thu, 25 Jan 2024 19:34:18 +0100 Subject: [PATCH 1392/1444] New translations technical-specs.md (Vietnamese) --- .../current/stacks-academy/technical-specs.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/i18n/vi/docusaurus-plugin-content-docs/current/stacks-academy/technical-specs.md b/i18n/vi/docusaurus-plugin-content-docs/current/stacks-academy/technical-specs.md index 695f849e1a..6f9fe1599e 100644 --- a/i18n/vi/docusaurus-plugin-content-docs/current/stacks-academy/technical-specs.md +++ b/i18n/vi/docusaurus-plugin-content-docs/current/stacks-academy/technical-specs.md @@ -40,7 +40,7 @@ sidebar_position: 13 - 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. +- All 4 address types are supported: Legacy, SegWit, Native SegWit, and Taproot - Further reading: [Stacking](stacking) ## Accounts and Addresses From 49bc5ec4185d076dfcec1026750559c83daf986c Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Thu, 25 Jan 2024 19:34:19 +0100 Subject: [PATCH 1393/1444] New translations stacking-contract.md (Vietnamese) --- .../current/clarity/noteworthy-contracts/stacking-contract.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/i18n/vi/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/stacking-contract.md b/i18n/vi/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/stacking-contract.md index c0027256cd..6a204159d3 100644 --- a/i18n/vi/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/stacking-contract.md +++ b/i18n/vi/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/stacking-contract.md @@ -145,7 +145,7 @@ 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 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. From d2bfa3b751240e35b539ee4fe315baf610bffa0c Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Thu, 25 Jan 2024 19:34:20 +0100 Subject: [PATCH 1394/1444] New translations stacking.md (Portuguese, Brazilian) --- .../current/stacks-academy/stacking.md | 10 ++++------ 1 file changed, 4 insertions(+), 6 deletions(-) diff --git a/i18n/pt/docusaurus-plugin-content-docs/current/stacks-academy/stacking.md b/i18n/pt/docusaurus-plugin-content-docs/current/stacks-academy/stacking.md index 3062c395ba..a1bcf9206e 100644 --- a/i18n/pt/docusaurus-plugin-content-docs/current/stacks-academy/stacking.md +++ b/i18n/pt/docusaurus-plugin-content-docs/current/stacks-academy/stacking.md @@ -85,7 +85,7 @@ Stacks (STX) token holders don't automatically receive stacking rewards. Instead - 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) +- 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. @@ -109,11 +109,9 @@ Stacking is a built-in capability of PoX and occurs through a set of actions on ## 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. ::: +:::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. From 356b5405c082e15b703017c66764ac639aad5cc4 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Thu, 25 Jan 2024 19:34:21 +0100 Subject: [PATCH 1395/1444] New translations technical-specs.md (Portuguese, Brazilian) --- .../current/stacks-academy/technical-specs.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/i18n/pt/docusaurus-plugin-content-docs/current/stacks-academy/technical-specs.md b/i18n/pt/docusaurus-plugin-content-docs/current/stacks-academy/technical-specs.md index 695f849e1a..6f9fe1599e 100644 --- a/i18n/pt/docusaurus-plugin-content-docs/current/stacks-academy/technical-specs.md +++ b/i18n/pt/docusaurus-plugin-content-docs/current/stacks-academy/technical-specs.md @@ -40,7 +40,7 @@ sidebar_position: 13 - 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. +- All 4 address types are supported: Legacy, SegWit, Native SegWit, and Taproot - Further reading: [Stacking](stacking) ## Accounts and Addresses From f323e3d79c324f8a984a44a288a130725a715000 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Thu, 25 Jan 2024 19:34:23 +0100 Subject: [PATCH 1396/1444] New translations stacking-contract.md (Portuguese, Brazilian) --- .../current/clarity/noteworthy-contracts/stacking-contract.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/i18n/pt/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/stacking-contract.md b/i18n/pt/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/stacking-contract.md index f58c4a86bd..f097d00764 100644 --- a/i18n/pt/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/stacking-contract.md +++ b/i18n/pt/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/stacking-contract.md @@ -145,7 +145,7 @@ 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 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. From 063ec74d9869876a9b95c55416a7b8ca9289eb3c Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Thu, 25 Jan 2024 19:34:24 +0100 Subject: [PATCH 1397/1444] New translations stacking.md (Indonesian) --- .../current/stacks-academy/stacking.md | 10 ++++------ 1 file changed, 4 insertions(+), 6 deletions(-) diff --git a/i18n/id/docusaurus-plugin-content-docs/current/stacks-academy/stacking.md b/i18n/id/docusaurus-plugin-content-docs/current/stacks-academy/stacking.md index b4b3c6e8db..3e5ef46947 100644 --- a/i18n/id/docusaurus-plugin-content-docs/current/stacks-academy/stacking.md +++ b/i18n/id/docusaurus-plugin-content-docs/current/stacks-academy/stacking.md @@ -85,7 +85,7 @@ Pemegang token Stacks (STX) tidak secara otomatis menerima hadiah stacking. Seba - 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) +- Provide a supported Bitcoin address to receive rewards (p2pkh, p2sh, SegWit, or Taproot) 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. @@ -109,11 +109,9 @@ Stacking adalah kemampuan bawaan PoX dan terjadi melalui serangkaian tindakan pa ## 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. ::: +:::note +Currently, all 4 address types are supported: Legacy, SegWit, Native SegWit, and Taproot. +::: 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. From b64e8f5ab312cafa726551f4a91d032162db1a01 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Thu, 25 Jan 2024 19:34:25 +0100 Subject: [PATCH 1398/1444] New translations technical-specs.md (Indonesian) --- .../current/stacks-academy/technical-specs.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/i18n/id/docusaurus-plugin-content-docs/current/stacks-academy/technical-specs.md b/i18n/id/docusaurus-plugin-content-docs/current/stacks-academy/technical-specs.md index c86954a037..10b68c6e4f 100644 --- a/i18n/id/docusaurus-plugin-content-docs/current/stacks-academy/technical-specs.md +++ b/i18n/id/docusaurus-plugin-content-docs/current/stacks-academy/technical-specs.md @@ -40,7 +40,7 @@ sidebar_position: 13 - 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. +- All 4 address types are supported: Legacy, SegWit, Native SegWit, and Taproot - Further reading: [Stacking](stacking) ## Akun dan Alamat From 188aad2834c6250d3c9a59e72125f69bc1918058 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Thu, 25 Jan 2024 19:34:26 +0100 Subject: [PATCH 1399/1444] New translations stacking-contract.md (Indonesian) --- .../current/clarity/noteworthy-contracts/stacking-contract.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/i18n/id/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/stacking-contract.md b/i18n/id/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/stacking-contract.md index 43abda2683..341ab34b1d 100644 --- a/i18n/id/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/stacking-contract.md +++ b/i18n/id/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/stacking-contract.md @@ -145,7 +145,7 @@ 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 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. From f75b7e1e3a229e00c242e5d31ed80a8c7fe213dc Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Thu, 25 Jan 2024 19:34:27 +0100 Subject: [PATCH 1400/1444] New translations stacking.md (Hindi) --- .../current/stacks-academy/stacking.md | 10 ++++------ 1 file changed, 4 insertions(+), 6 deletions(-) diff --git a/i18n/hi/docusaurus-plugin-content-docs/current/stacks-academy/stacking.md b/i18n/hi/docusaurus-plugin-content-docs/current/stacks-academy/stacking.md index a530bca651..a6f9b9ac96 100644 --- a/i18n/hi/docusaurus-plugin-content-docs/current/stacks-academy/stacking.md +++ b/i18n/hi/docusaurus-plugin-content-docs/current/stacks-academy/stacking.md @@ -85,7 +85,7 @@ Stacks (STX) token holders don't automatically receive stacking rewards. Instead - 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) +- 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. @@ -109,11 +109,9 @@ Stacking is a built-in capability of PoX and occurs through a set of actions on ## 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. ::: +:::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. From ed788a950553011b226ce85326879cd10c00e987 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Thu, 25 Jan 2024 19:34:28 +0100 Subject: [PATCH 1401/1444] New translations technical-specs.md (Hindi) --- .../current/stacks-academy/technical-specs.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/i18n/hi/docusaurus-plugin-content-docs/current/stacks-academy/technical-specs.md b/i18n/hi/docusaurus-plugin-content-docs/current/stacks-academy/technical-specs.md index 695f849e1a..6f9fe1599e 100644 --- a/i18n/hi/docusaurus-plugin-content-docs/current/stacks-academy/technical-specs.md +++ b/i18n/hi/docusaurus-plugin-content-docs/current/stacks-academy/technical-specs.md @@ -40,7 +40,7 @@ sidebar_position: 13 - 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. +- All 4 address types are supported: Legacy, SegWit, Native SegWit, and Taproot - Further reading: [Stacking](stacking) ## Accounts and Addresses From 24302efb232012236ee4624b5ca6fcdd7d5d3dcd Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Thu, 25 Jan 2024 19:34:29 +0100 Subject: [PATCH 1402/1444] New translations stacking-contract.md (Hindi) --- .../current/clarity/noteworthy-contracts/stacking-contract.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/i18n/hi/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/stacking-contract.md b/i18n/hi/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/stacking-contract.md index c0027256cd..6a204159d3 100644 --- a/i18n/hi/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/stacking-contract.md +++ b/i18n/hi/docusaurus-plugin-content-docs/current/clarity/noteworthy-contracts/stacking-contract.md @@ -145,7 +145,7 @@ 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 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. From 8c9bd5027d79e266e2d9850078219682fa59d6ba Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Thu, 25 Jan 2024 20:33:07 +0100 Subject: [PATCH 1403/1444] Update source file stacking-contract.md --- docs/clarity/noteworthy-contracts/stacking-contract.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/clarity/noteworthy-contracts/stacking-contract.md b/docs/clarity/noteworthy-contracts/stacking-contract.md index c0027256cd..6a204159d3 100644 --- a/docs/clarity/noteworthy-contracts/stacking-contract.md +++ b/docs/clarity/noteworthy-contracts/stacking-contract.md @@ -145,7 +145,7 @@ 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 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. From 4357f173c63a5663c9f7726a97f0fba7f4740c75 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Thu, 25 Jan 2024 20:33:19 +0100 Subject: [PATCH 1404/1444] Update source file stacking.md --- docs/stacks-academy/stacking.md | 12 ++++-------- 1 file changed, 4 insertions(+), 8 deletions(-) diff --git a/docs/stacks-academy/stacking.md b/docs/stacks-academy/stacking.md index 5be30ea145..846152ecf9 100644 --- a/docs/stacks-academy/stacking.md +++ b/docs/stacks-academy/stacking.md @@ -89,7 +89,7 @@ Stacks (STX) token holders don't automatically receive stacking rewards. Instead - 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) +- 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. @@ -114,13 +114,9 @@ Stacking is a built-in capability of PoX and occurs through a set of actions on ## 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. - ::: +:::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. From 20cbd7427a333a1cbfb26c372e83f51eb84e9156 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Thu, 25 Jan 2024 20:33:20 +0100 Subject: [PATCH 1405/1444] Update source file technical-specs.md --- docs/stacks-academy/technical-specs.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/stacks-academy/technical-specs.md b/docs/stacks-academy/technical-specs.md index 695f849e1a..6f9fe1599e 100644 --- a/docs/stacks-academy/technical-specs.md +++ b/docs/stacks-academy/technical-specs.md @@ -40,7 +40,7 @@ sidebar_position: 13 - 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. +- All 4 address types are supported: Legacy, SegWit, Native SegWit, and Taproot - Further reading: [Stacking](stacking) ## Accounts and Addresses From 56580b525667712f59027074d302aec97c0056a4 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Wed, 31 Jan 2024 23:26:37 +0100 Subject: [PATCH 1406/1444] New translations signer.md (French) --- .../current/nakamoto/signer.md | 149 ++++++++++++++++++ 1 file changed, 149 insertions(+) create mode 100644 i18n/fr/docusaurus-plugin-content-docs/current/nakamoto/signer.md diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/nakamoto/signer.md b/i18n/fr/docusaurus-plugin-content-docs/current/nakamoto/signer.md new file mode 100644 index 0000000000..b80db1b7fc --- /dev/null +++ b/i18n/fr/docusaurus-plugin-content-docs/current/nakamoto/signer.md @@ -0,0 +1,149 @@ +--- +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 offhand From 307a7f510c790e52df2eb609345d978d78ecfd58 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Wed, 31 Jan 2024 23:26:40 +0100 Subject: [PATCH 1407/1444] New translations signer.md (Spanish) --- .../current/nakamoto/signer.md | 149 ++++++++++++++++++ 1 file changed, 149 insertions(+) create mode 100644 i18n/es/docusaurus-plugin-content-docs/current/nakamoto/signer.md diff --git a/i18n/es/docusaurus-plugin-content-docs/current/nakamoto/signer.md b/i18n/es/docusaurus-plugin-content-docs/current/nakamoto/signer.md new file mode 100644 index 0000000000..b80db1b7fc --- /dev/null +++ b/i18n/es/docusaurus-plugin-content-docs/current/nakamoto/signer.md @@ -0,0 +1,149 @@ +--- +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 offhand From c12afffadd70d1453c3548ea7156c385311fa811 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Wed, 31 Jan 2024 23:26:44 +0100 Subject: [PATCH 1408/1444] New translations signer.md (German) --- .../current/nakamoto/signer.md | 149 ++++++++++++++++++ 1 file changed, 149 insertions(+) create mode 100644 i18n/de/docusaurus-plugin-content-docs/current/nakamoto/signer.md diff --git a/i18n/de/docusaurus-plugin-content-docs/current/nakamoto/signer.md b/i18n/de/docusaurus-plugin-content-docs/current/nakamoto/signer.md new file mode 100644 index 0000000000..b80db1b7fc --- /dev/null +++ b/i18n/de/docusaurus-plugin-content-docs/current/nakamoto/signer.md @@ -0,0 +1,149 @@ +--- +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 offhand From e5da0c4cabf797a20270228b56fb6c5d88581f53 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Wed, 31 Jan 2024 23:26:46 +0100 Subject: [PATCH 1409/1444] New translations signer.md (Japanese) --- .../current/nakamoto/signer.md | 149 ++++++++++++++++++ 1 file changed, 149 insertions(+) create mode 100644 i18n/ja/docusaurus-plugin-content-docs/current/nakamoto/signer.md diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/nakamoto/signer.md b/i18n/ja/docusaurus-plugin-content-docs/current/nakamoto/signer.md new file mode 100644 index 0000000000..b80db1b7fc --- /dev/null +++ b/i18n/ja/docusaurus-plugin-content-docs/current/nakamoto/signer.md @@ -0,0 +1,149 @@ +--- +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 offhand From d069ba7d8f23aaadf7a34965136d600641b0ecbe Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Wed, 31 Jan 2024 23:26:49 +0100 Subject: [PATCH 1410/1444] New translations signer.md (Korean) --- .../current/nakamoto/signer.md | 149 ++++++++++++++++++ 1 file changed, 149 insertions(+) create mode 100644 i18n/ko/docusaurus-plugin-content-docs/current/nakamoto/signer.md diff --git a/i18n/ko/docusaurus-plugin-content-docs/current/nakamoto/signer.md b/i18n/ko/docusaurus-plugin-content-docs/current/nakamoto/signer.md new file mode 100644 index 0000000000..b80db1b7fc --- /dev/null +++ b/i18n/ko/docusaurus-plugin-content-docs/current/nakamoto/signer.md @@ -0,0 +1,149 @@ +--- +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 offhand From c6ae9192681a2a933ba404259ccf1439f97e794d Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Wed, 31 Jan 2024 23:26:52 +0100 Subject: [PATCH 1411/1444] New translations signer.md (Russian) --- .../current/nakamoto/signer.md | 149 ++++++++++++++++++ 1 file changed, 149 insertions(+) create mode 100644 i18n/ru/docusaurus-plugin-content-docs/current/nakamoto/signer.md diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/nakamoto/signer.md b/i18n/ru/docusaurus-plugin-content-docs/current/nakamoto/signer.md new file mode 100644 index 0000000000..b80db1b7fc --- /dev/null +++ b/i18n/ru/docusaurus-plugin-content-docs/current/nakamoto/signer.md @@ -0,0 +1,149 @@ +--- +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 offhand From 860fc17de03f09f8978571556a0a2d14f468fdf4 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Wed, 31 Jan 2024 23:26:55 +0100 Subject: [PATCH 1412/1444] New translations signer.md (Turkish) --- .../current/nakamoto/signer.md | 149 ++++++++++++++++++ 1 file changed, 149 insertions(+) create mode 100644 i18n/tr/docusaurus-plugin-content-docs/current/nakamoto/signer.md diff --git a/i18n/tr/docusaurus-plugin-content-docs/current/nakamoto/signer.md b/i18n/tr/docusaurus-plugin-content-docs/current/nakamoto/signer.md new file mode 100644 index 0000000000..b80db1b7fc --- /dev/null +++ b/i18n/tr/docusaurus-plugin-content-docs/current/nakamoto/signer.md @@ -0,0 +1,149 @@ +--- +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 offhand From 3711d8bd9dd5d9ae834a3cf5d36344ee1669ba0c Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Wed, 31 Jan 2024 23:26:58 +0100 Subject: [PATCH 1413/1444] New translations signer.md (Chinese Simplified) --- .../current/nakamoto/signer.md | 149 ++++++++++++++++++ 1 file changed, 149 insertions(+) create mode 100644 i18n/zh/docusaurus-plugin-content-docs/current/nakamoto/signer.md diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/nakamoto/signer.md b/i18n/zh/docusaurus-plugin-content-docs/current/nakamoto/signer.md new file mode 100644 index 0000000000..b80db1b7fc --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/current/nakamoto/signer.md @@ -0,0 +1,149 @@ +--- +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 offhand From 2b2508c3b5c19cb99d4d590cc60b06756c7f53f9 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Wed, 31 Jan 2024 23:27:01 +0100 Subject: [PATCH 1414/1444] New translations signer.md (Vietnamese) --- .../current/nakamoto/signer.md | 149 ++++++++++++++++++ 1 file changed, 149 insertions(+) create mode 100644 i18n/vi/docusaurus-plugin-content-docs/current/nakamoto/signer.md diff --git a/i18n/vi/docusaurus-plugin-content-docs/current/nakamoto/signer.md b/i18n/vi/docusaurus-plugin-content-docs/current/nakamoto/signer.md new file mode 100644 index 0000000000..b80db1b7fc --- /dev/null +++ b/i18n/vi/docusaurus-plugin-content-docs/current/nakamoto/signer.md @@ -0,0 +1,149 @@ +--- +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 offhand From d1eadc9441475b62c2a237c51b86396ca14ad124 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Wed, 31 Jan 2024 23:27:04 +0100 Subject: [PATCH 1415/1444] New translations signer.md (Portuguese, Brazilian) --- .../current/nakamoto/signer.md | 149 ++++++++++++++++++ 1 file changed, 149 insertions(+) create mode 100644 i18n/pt/docusaurus-plugin-content-docs/current/nakamoto/signer.md diff --git a/i18n/pt/docusaurus-plugin-content-docs/current/nakamoto/signer.md b/i18n/pt/docusaurus-plugin-content-docs/current/nakamoto/signer.md new file mode 100644 index 0000000000..b80db1b7fc --- /dev/null +++ b/i18n/pt/docusaurus-plugin-content-docs/current/nakamoto/signer.md @@ -0,0 +1,149 @@ +--- +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 offhand From 8c03be60283a6206c52b44e921c04682e70ea47d Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Wed, 31 Jan 2024 23:27:07 +0100 Subject: [PATCH 1416/1444] New translations signer.md (Indonesian) --- .../current/nakamoto/signer.md | 149 ++++++++++++++++++ 1 file changed, 149 insertions(+) create mode 100644 i18n/id/docusaurus-plugin-content-docs/current/nakamoto/signer.md diff --git a/i18n/id/docusaurus-plugin-content-docs/current/nakamoto/signer.md b/i18n/id/docusaurus-plugin-content-docs/current/nakamoto/signer.md new file mode 100644 index 0000000000..b80db1b7fc --- /dev/null +++ b/i18n/id/docusaurus-plugin-content-docs/current/nakamoto/signer.md @@ -0,0 +1,149 @@ +--- +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 offhand From e3020fa18bdea30e5555835afa5392cc1f47001f Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Wed, 31 Jan 2024 23:27:11 +0100 Subject: [PATCH 1417/1444] New translations signer.md (Hindi) --- .../current/nakamoto/signer.md | 149 ++++++++++++++++++ 1 file changed, 149 insertions(+) create mode 100644 i18n/hi/docusaurus-plugin-content-docs/current/nakamoto/signer.md diff --git a/i18n/hi/docusaurus-plugin-content-docs/current/nakamoto/signer.md b/i18n/hi/docusaurus-plugin-content-docs/current/nakamoto/signer.md new file mode 100644 index 0000000000..b80db1b7fc --- /dev/null +++ b/i18n/hi/docusaurus-plugin-content-docs/current/nakamoto/signer.md @@ -0,0 +1,149 @@ +--- +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 offhand From 870da6d68b6ccee41275ddfdcef7243ab8055fa1 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Thu, 1 Feb 2024 07:30:17 +0100 Subject: [PATCH 1418/1444] Update source file signer.md --- docs/nakamoto/signer.md | 149 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 149 insertions(+) create mode 100644 docs/nakamoto/signer.md diff --git a/docs/nakamoto/signer.md b/docs/nakamoto/signer.md new file mode 100644 index 0000000000..61138f1330 --- /dev/null +++ b/docs/nakamoto/signer.md @@ -0,0 +1,149 @@ +--- +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 offhand From ad5c69b2c084b1583ccd6602a3799ec008d9ccf6 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Fri, 2 Feb 2024 20:35:01 +0100 Subject: [PATCH 1419/1444] New translations signer.md (French) --- .../docusaurus-plugin-content-docs/current/nakamoto/signer.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/nakamoto/signer.md b/i18n/fr/docusaurus-plugin-content-docs/current/nakamoto/signer.md index b80db1b7fc..519e271d08 100644 --- a/i18n/fr/docusaurus-plugin-content-docs/current/nakamoto/signer.md +++ b/i18n/fr/docusaurus-plugin-content-docs/current/nakamoto/signer.md @@ -146,4 +146,4 @@ CMD ["stacks-signer", "run", "--config", "/config/signer.toml"] 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 offhand +Minimum Requirements: run a full node, run the signer binary. 1 cpu, 4gb of ram, 150GB of storage as a minimum. From 4bf40f68369ea95b6e5aea5457673949365eb414 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Fri, 2 Feb 2024 20:35:02 +0100 Subject: [PATCH 1420/1444] New translations signer.md (Spanish) --- .../docusaurus-plugin-content-docs/current/nakamoto/signer.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/i18n/es/docusaurus-plugin-content-docs/current/nakamoto/signer.md b/i18n/es/docusaurus-plugin-content-docs/current/nakamoto/signer.md index b80db1b7fc..519e271d08 100644 --- a/i18n/es/docusaurus-plugin-content-docs/current/nakamoto/signer.md +++ b/i18n/es/docusaurus-plugin-content-docs/current/nakamoto/signer.md @@ -146,4 +146,4 @@ CMD ["stacks-signer", "run", "--config", "/config/signer.toml"] 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 offhand +Minimum Requirements: run a full node, run the signer binary. 1 cpu, 4gb of ram, 150GB of storage as a minimum. From 243a0257a5fce4e8a9d5d889543a98982f3a38cc Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Fri, 2 Feb 2024 20:35:04 +0100 Subject: [PATCH 1421/1444] New translations signer.md (German) --- .../docusaurus-plugin-content-docs/current/nakamoto/signer.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/i18n/de/docusaurus-plugin-content-docs/current/nakamoto/signer.md b/i18n/de/docusaurus-plugin-content-docs/current/nakamoto/signer.md index b80db1b7fc..519e271d08 100644 --- a/i18n/de/docusaurus-plugin-content-docs/current/nakamoto/signer.md +++ b/i18n/de/docusaurus-plugin-content-docs/current/nakamoto/signer.md @@ -146,4 +146,4 @@ CMD ["stacks-signer", "run", "--config", "/config/signer.toml"] 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 offhand +Minimum Requirements: run a full node, run the signer binary. 1 cpu, 4gb of ram, 150GB of storage as a minimum. From f496c4732e2d172d7ef05d4d2cf42fbc2c51245b Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Fri, 2 Feb 2024 20:35:05 +0100 Subject: [PATCH 1422/1444] New translations signer.md (Japanese) --- .../docusaurus-plugin-content-docs/current/nakamoto/signer.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/nakamoto/signer.md b/i18n/ja/docusaurus-plugin-content-docs/current/nakamoto/signer.md index b80db1b7fc..519e271d08 100644 --- a/i18n/ja/docusaurus-plugin-content-docs/current/nakamoto/signer.md +++ b/i18n/ja/docusaurus-plugin-content-docs/current/nakamoto/signer.md @@ -146,4 +146,4 @@ CMD ["stacks-signer", "run", "--config", "/config/signer.toml"] 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 offhand +Minimum Requirements: run a full node, run the signer binary. 1 cpu, 4gb of ram, 150GB of storage as a minimum. From 2ac992d2637302aa4c3ceb00417c383b81c3429f Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Fri, 2 Feb 2024 20:35:06 +0100 Subject: [PATCH 1423/1444] New translations signer.md (Korean) --- .../docusaurus-plugin-content-docs/current/nakamoto/signer.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/i18n/ko/docusaurus-plugin-content-docs/current/nakamoto/signer.md b/i18n/ko/docusaurus-plugin-content-docs/current/nakamoto/signer.md index b80db1b7fc..519e271d08 100644 --- a/i18n/ko/docusaurus-plugin-content-docs/current/nakamoto/signer.md +++ b/i18n/ko/docusaurus-plugin-content-docs/current/nakamoto/signer.md @@ -146,4 +146,4 @@ CMD ["stacks-signer", "run", "--config", "/config/signer.toml"] 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 offhand +Minimum Requirements: run a full node, run the signer binary. 1 cpu, 4gb of ram, 150GB of storage as a minimum. From 23d18132a86800df746bdfe40994cba15691cf86 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Fri, 2 Feb 2024 20:35:07 +0100 Subject: [PATCH 1424/1444] New translations signer.md (Russian) --- .../docusaurus-plugin-content-docs/current/nakamoto/signer.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/nakamoto/signer.md b/i18n/ru/docusaurus-plugin-content-docs/current/nakamoto/signer.md index b80db1b7fc..519e271d08 100644 --- a/i18n/ru/docusaurus-plugin-content-docs/current/nakamoto/signer.md +++ b/i18n/ru/docusaurus-plugin-content-docs/current/nakamoto/signer.md @@ -146,4 +146,4 @@ CMD ["stacks-signer", "run", "--config", "/config/signer.toml"] 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 offhand +Minimum Requirements: run a full node, run the signer binary. 1 cpu, 4gb of ram, 150GB of storage as a minimum. From 019f50b9f860b62536da56950b293226496b15f5 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Fri, 2 Feb 2024 20:35:08 +0100 Subject: [PATCH 1425/1444] New translations signer.md (Turkish) --- .../docusaurus-plugin-content-docs/current/nakamoto/signer.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/i18n/tr/docusaurus-plugin-content-docs/current/nakamoto/signer.md b/i18n/tr/docusaurus-plugin-content-docs/current/nakamoto/signer.md index b80db1b7fc..519e271d08 100644 --- a/i18n/tr/docusaurus-plugin-content-docs/current/nakamoto/signer.md +++ b/i18n/tr/docusaurus-plugin-content-docs/current/nakamoto/signer.md @@ -146,4 +146,4 @@ CMD ["stacks-signer", "run", "--config", "/config/signer.toml"] 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 offhand +Minimum Requirements: run a full node, run the signer binary. 1 cpu, 4gb of ram, 150GB of storage as a minimum. From 06ad192a2c0185f2f3382c0203e4b3b1f0f7b362 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Fri, 2 Feb 2024 20:35:09 +0100 Subject: [PATCH 1426/1444] New translations signer.md (Chinese Simplified) --- .../docusaurus-plugin-content-docs/current/nakamoto/signer.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/nakamoto/signer.md b/i18n/zh/docusaurus-plugin-content-docs/current/nakamoto/signer.md index b80db1b7fc..519e271d08 100644 --- a/i18n/zh/docusaurus-plugin-content-docs/current/nakamoto/signer.md +++ b/i18n/zh/docusaurus-plugin-content-docs/current/nakamoto/signer.md @@ -146,4 +146,4 @@ CMD ["stacks-signer", "run", "--config", "/config/signer.toml"] 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 offhand +Minimum Requirements: run a full node, run the signer binary. 1 cpu, 4gb of ram, 150GB of storage as a minimum. From e2d433e83713f6943a471180d4631fb69905f3e2 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Fri, 2 Feb 2024 20:35:10 +0100 Subject: [PATCH 1427/1444] New translations signer.md (Vietnamese) --- .../docusaurus-plugin-content-docs/current/nakamoto/signer.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/i18n/vi/docusaurus-plugin-content-docs/current/nakamoto/signer.md b/i18n/vi/docusaurus-plugin-content-docs/current/nakamoto/signer.md index b80db1b7fc..519e271d08 100644 --- a/i18n/vi/docusaurus-plugin-content-docs/current/nakamoto/signer.md +++ b/i18n/vi/docusaurus-plugin-content-docs/current/nakamoto/signer.md @@ -146,4 +146,4 @@ CMD ["stacks-signer", "run", "--config", "/config/signer.toml"] 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 offhand +Minimum Requirements: run a full node, run the signer binary. 1 cpu, 4gb of ram, 150GB of storage as a minimum. From 71ef495b0766c7b8ec0bffc647bbf7539f41442b Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Fri, 2 Feb 2024 20:35:11 +0100 Subject: [PATCH 1428/1444] New translations signer.md (Portuguese, Brazilian) --- .../docusaurus-plugin-content-docs/current/nakamoto/signer.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/i18n/pt/docusaurus-plugin-content-docs/current/nakamoto/signer.md b/i18n/pt/docusaurus-plugin-content-docs/current/nakamoto/signer.md index b80db1b7fc..519e271d08 100644 --- a/i18n/pt/docusaurus-plugin-content-docs/current/nakamoto/signer.md +++ b/i18n/pt/docusaurus-plugin-content-docs/current/nakamoto/signer.md @@ -146,4 +146,4 @@ CMD ["stacks-signer", "run", "--config", "/config/signer.toml"] 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 offhand +Minimum Requirements: run a full node, run the signer binary. 1 cpu, 4gb of ram, 150GB of storage as a minimum. From 76d8676687261c29fad68144361d78d8ae26b0c6 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Fri, 2 Feb 2024 20:35:12 +0100 Subject: [PATCH 1429/1444] New translations signer.md (Indonesian) --- .../docusaurus-plugin-content-docs/current/nakamoto/signer.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/i18n/id/docusaurus-plugin-content-docs/current/nakamoto/signer.md b/i18n/id/docusaurus-plugin-content-docs/current/nakamoto/signer.md index b80db1b7fc..519e271d08 100644 --- a/i18n/id/docusaurus-plugin-content-docs/current/nakamoto/signer.md +++ b/i18n/id/docusaurus-plugin-content-docs/current/nakamoto/signer.md @@ -146,4 +146,4 @@ CMD ["stacks-signer", "run", "--config", "/config/signer.toml"] 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 offhand +Minimum Requirements: run a full node, run the signer binary. 1 cpu, 4gb of ram, 150GB of storage as a minimum. From f56a695d240bceeee78b7e01edabe54c141c4f2a Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Fri, 2 Feb 2024 20:35:13 +0100 Subject: [PATCH 1430/1444] New translations signer.md (Hindi) --- .../docusaurus-plugin-content-docs/current/nakamoto/signer.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/i18n/hi/docusaurus-plugin-content-docs/current/nakamoto/signer.md b/i18n/hi/docusaurus-plugin-content-docs/current/nakamoto/signer.md index b80db1b7fc..519e271d08 100644 --- a/i18n/hi/docusaurus-plugin-content-docs/current/nakamoto/signer.md +++ b/i18n/hi/docusaurus-plugin-content-docs/current/nakamoto/signer.md @@ -146,4 +146,4 @@ CMD ["stacks-signer", "run", "--config", "/config/signer.toml"] 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 offhand +Minimum Requirements: run a full node, run the signer binary. 1 cpu, 4gb of ram, 150GB of storage as a minimum. From e1df47e6f14ad390ebfc0818a7431d8897e501d2 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Fri, 2 Feb 2024 20:35:15 +0100 Subject: [PATCH 1431/1444] New translations stacking.md (French) --- .../current/nakamoto/stacking.md | 174 ++++++++++++++++++ 1 file changed, 174 insertions(+) create mode 100644 i18n/fr/docusaurus-plugin-content-docs/current/nakamoto/stacking.md diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/nakamoto/stacking.md b/i18n/fr/docusaurus-plugin-content-docs/current/nakamoto/stacking.md new file mode 100644 index 0000000000..4c5c22f647 --- /dev/null +++ b/i18n/fr/docusaurus-plugin-content-docs/current/nakamoto/stacking.md @@ -0,0 +1,174 @@ +--- +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 From b60abee5be373459a6e0659cc3b59cea9b27a65d Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Fri, 2 Feb 2024 20:35:17 +0100 Subject: [PATCH 1432/1444] New translations stacking.md (Spanish) --- .../current/nakamoto/stacking.md | 174 ++++++++++++++++++ 1 file changed, 174 insertions(+) create mode 100644 i18n/es/docusaurus-plugin-content-docs/current/nakamoto/stacking.md diff --git a/i18n/es/docusaurus-plugin-content-docs/current/nakamoto/stacking.md b/i18n/es/docusaurus-plugin-content-docs/current/nakamoto/stacking.md new file mode 100644 index 0000000000..4c5c22f647 --- /dev/null +++ b/i18n/es/docusaurus-plugin-content-docs/current/nakamoto/stacking.md @@ -0,0 +1,174 @@ +--- +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 From eb25a5e59513836d733b4936c95dd9e290f095f7 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Fri, 2 Feb 2024 20:35:19 +0100 Subject: [PATCH 1433/1444] New translations stacking.md (German) --- .../current/nakamoto/stacking.md | 174 ++++++++++++++++++ 1 file changed, 174 insertions(+) create mode 100644 i18n/de/docusaurus-plugin-content-docs/current/nakamoto/stacking.md diff --git a/i18n/de/docusaurus-plugin-content-docs/current/nakamoto/stacking.md b/i18n/de/docusaurus-plugin-content-docs/current/nakamoto/stacking.md new file mode 100644 index 0000000000..4c5c22f647 --- /dev/null +++ b/i18n/de/docusaurus-plugin-content-docs/current/nakamoto/stacking.md @@ -0,0 +1,174 @@ +--- +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 From 34d8707779d68fc70d4f5a4a6086215b87f9e360 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Fri, 2 Feb 2024 20:35:21 +0100 Subject: [PATCH 1434/1444] New translations stacking.md (Japanese) --- .../current/nakamoto/stacking.md | 174 ++++++++++++++++++ 1 file changed, 174 insertions(+) create mode 100644 i18n/ja/docusaurus-plugin-content-docs/current/nakamoto/stacking.md diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/nakamoto/stacking.md b/i18n/ja/docusaurus-plugin-content-docs/current/nakamoto/stacking.md new file mode 100644 index 0000000000..4c5c22f647 --- /dev/null +++ b/i18n/ja/docusaurus-plugin-content-docs/current/nakamoto/stacking.md @@ -0,0 +1,174 @@ +--- +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 From 4ac97455ae6724cb4bf7c6e91a11f17796ac8df7 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Fri, 2 Feb 2024 20:35:23 +0100 Subject: [PATCH 1435/1444] New translations stacking.md (Korean) --- .../current/nakamoto/stacking.md | 174 ++++++++++++++++++ 1 file changed, 174 insertions(+) create mode 100644 i18n/ko/docusaurus-plugin-content-docs/current/nakamoto/stacking.md diff --git a/i18n/ko/docusaurus-plugin-content-docs/current/nakamoto/stacking.md b/i18n/ko/docusaurus-plugin-content-docs/current/nakamoto/stacking.md new file mode 100644 index 0000000000..4c5c22f647 --- /dev/null +++ b/i18n/ko/docusaurus-plugin-content-docs/current/nakamoto/stacking.md @@ -0,0 +1,174 @@ +--- +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 From 715f6103b81181e822c9b3a8211e6f5daa269782 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Fri, 2 Feb 2024 20:35:26 +0100 Subject: [PATCH 1436/1444] New translations stacking.md (Russian) --- .../current/nakamoto/stacking.md | 174 ++++++++++++++++++ 1 file changed, 174 insertions(+) create mode 100644 i18n/ru/docusaurus-plugin-content-docs/current/nakamoto/stacking.md diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/nakamoto/stacking.md b/i18n/ru/docusaurus-plugin-content-docs/current/nakamoto/stacking.md new file mode 100644 index 0000000000..4c5c22f647 --- /dev/null +++ b/i18n/ru/docusaurus-plugin-content-docs/current/nakamoto/stacking.md @@ -0,0 +1,174 @@ +--- +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 From 2fc1385bc96ac1e24ffd01ec5277174eae0b1b65 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Fri, 2 Feb 2024 20:35:27 +0100 Subject: [PATCH 1437/1444] New translations stacking.md (Turkish) --- .../current/nakamoto/stacking.md | 174 ++++++++++++++++++ 1 file changed, 174 insertions(+) create mode 100644 i18n/tr/docusaurus-plugin-content-docs/current/nakamoto/stacking.md diff --git a/i18n/tr/docusaurus-plugin-content-docs/current/nakamoto/stacking.md b/i18n/tr/docusaurus-plugin-content-docs/current/nakamoto/stacking.md new file mode 100644 index 0000000000..4c5c22f647 --- /dev/null +++ b/i18n/tr/docusaurus-plugin-content-docs/current/nakamoto/stacking.md @@ -0,0 +1,174 @@ +--- +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 From e1c03b075b4048915d9cb6f4cc06cb35df8df628 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Fri, 2 Feb 2024 20:35:29 +0100 Subject: [PATCH 1438/1444] New translations stacking.md (Chinese Simplified) --- .../current/nakamoto/stacking.md | 174 ++++++++++++++++++ 1 file changed, 174 insertions(+) create mode 100644 i18n/zh/docusaurus-plugin-content-docs/current/nakamoto/stacking.md diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/nakamoto/stacking.md b/i18n/zh/docusaurus-plugin-content-docs/current/nakamoto/stacking.md new file mode 100644 index 0000000000..4c5c22f647 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/current/nakamoto/stacking.md @@ -0,0 +1,174 @@ +--- +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 From 7d1c2fac25a27e5f8b0d656f2ed122b8ae19728b Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Fri, 2 Feb 2024 20:35:31 +0100 Subject: [PATCH 1439/1444] New translations stacking.md (Vietnamese) --- .../current/nakamoto/stacking.md | 174 ++++++++++++++++++ 1 file changed, 174 insertions(+) create mode 100644 i18n/vi/docusaurus-plugin-content-docs/current/nakamoto/stacking.md diff --git a/i18n/vi/docusaurus-plugin-content-docs/current/nakamoto/stacking.md b/i18n/vi/docusaurus-plugin-content-docs/current/nakamoto/stacking.md new file mode 100644 index 0000000000..4c5c22f647 --- /dev/null +++ b/i18n/vi/docusaurus-plugin-content-docs/current/nakamoto/stacking.md @@ -0,0 +1,174 @@ +--- +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 From 5d65ebcebf4352b583608fddf5885d3046227500 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Fri, 2 Feb 2024 20:35:33 +0100 Subject: [PATCH 1440/1444] New translations stacking.md (Portuguese, Brazilian) --- .../current/nakamoto/stacking.md | 174 ++++++++++++++++++ 1 file changed, 174 insertions(+) create mode 100644 i18n/pt/docusaurus-plugin-content-docs/current/nakamoto/stacking.md diff --git a/i18n/pt/docusaurus-plugin-content-docs/current/nakamoto/stacking.md b/i18n/pt/docusaurus-plugin-content-docs/current/nakamoto/stacking.md new file mode 100644 index 0000000000..4c5c22f647 --- /dev/null +++ b/i18n/pt/docusaurus-plugin-content-docs/current/nakamoto/stacking.md @@ -0,0 +1,174 @@ +--- +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 From 6b0f15391454a39b7ceed750e7de27082e94a3a6 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Fri, 2 Feb 2024 20:35:35 +0100 Subject: [PATCH 1441/1444] New translations stacking.md (Indonesian) --- .../current/nakamoto/stacking.md | 174 ++++++++++++++++++ 1 file changed, 174 insertions(+) create mode 100644 i18n/id/docusaurus-plugin-content-docs/current/nakamoto/stacking.md diff --git a/i18n/id/docusaurus-plugin-content-docs/current/nakamoto/stacking.md b/i18n/id/docusaurus-plugin-content-docs/current/nakamoto/stacking.md new file mode 100644 index 0000000000..4c5c22f647 --- /dev/null +++ b/i18n/id/docusaurus-plugin-content-docs/current/nakamoto/stacking.md @@ -0,0 +1,174 @@ +--- +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 From 14ed41ada24be705327e5e5e86914c7f506452bf Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Fri, 2 Feb 2024 20:35:37 +0100 Subject: [PATCH 1442/1444] New translations stacking.md (Hindi) --- .../current/nakamoto/stacking.md | 174 ++++++++++++++++++ 1 file changed, 174 insertions(+) create mode 100644 i18n/hi/docusaurus-plugin-content-docs/current/nakamoto/stacking.md diff --git a/i18n/hi/docusaurus-plugin-content-docs/current/nakamoto/stacking.md b/i18n/hi/docusaurus-plugin-content-docs/current/nakamoto/stacking.md new file mode 100644 index 0000000000..4c5c22f647 --- /dev/null +++ b/i18n/hi/docusaurus-plugin-content-docs/current/nakamoto/stacking.md @@ -0,0 +1,174 @@ +--- +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 From e1aa7f424c2dca328ec63c5ff4d20b0a43792cd7 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Fri, 2 Feb 2024 21:31:44 +0100 Subject: [PATCH 1443/1444] Update source file signer.md --- docs/nakamoto/signer.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/nakamoto/signer.md b/docs/nakamoto/signer.md index 61138f1330..8f5f3d9921 100644 --- a/docs/nakamoto/signer.md +++ b/docs/nakamoto/signer.md @@ -146,4 +146,4 @@ CMD ["stacks-signer", "run", "--config", "/config/signer.toml"] 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 offhand +Minimum Requirements: run a full node, run the signer binary. 1 cpu, 4gb of ram, 150GB of storage as a minimum. From 4b57fa9a44bef4f0f99319457b584019871e5b33 Mon Sep 17 00:00:00 2001 From: bot-translations <104575519+bot-translations@users.noreply.github.com> Date: Fri, 2 Feb 2024 21:31:44 +0100 Subject: [PATCH 1444/1444] Update source file stacking.md --- docs/nakamoto/stacking.md | 174 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 174 insertions(+) create mode 100644 docs/nakamoto/stacking.md diff --git a/docs/nakamoto/stacking.md b/docs/nakamoto/stacking.md new file mode 100644 index 0000000000..4c5c22f647 --- /dev/null +++ b/docs/nakamoto/stacking.md @@ -0,0 +1,174 @@ +--- +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