diff --git a/content/docs/stacks/clarity/access-control.mdx b/content/docs/stacks/clarity/access-control.mdx index c90deca9..ff42f2a1 100644 --- a/content/docs/stacks/clarity/access-control.mdx +++ b/content/docs/stacks/clarity/access-control.mdx @@ -135,7 +135,7 @@ Clarity's principal functions are designed with blockchain-specific consideratio ) ``` -## Practical example: simple governance contract +## Practical example: Simple governance contract Let's implement a basic governance contract that demonstrates role-based access control using principal functions. This contract will have an owner, administrators, and regular members, each with different permissions. diff --git a/content/docs/stacks/clarity/basic-arithmetic.mdx b/content/docs/stacks/clarity/basic-arithmetic.mdx index c0292040..a06a6d47 100644 --- a/content/docs/stacks/clarity/basic-arithmetic.mdx +++ b/content/docs/stacks/clarity/basic-arithmetic.mdx @@ -136,7 +136,7 @@ Clarity's arithmetic functions are designed with blockchain-specific considerati 5. **Using uint vs int**: Choose `uint` for values that can't be negative (like token amounts) and `int` when negative values are possible. -## Practical example: simple interest calculator +## Practical example: Simple interest calculator Let's combine these functions to create a simple interest calculator: diff --git a/content/docs/stacks/clarity/bit-manipulation.mdx b/content/docs/stacks/clarity/bit-manipulation.mdx index 2b600496..5ecc5eeb 100644 --- a/content/docs/stacks/clarity/bit-manipulation.mdx +++ b/content/docs/stacks/clarity/bit-manipulation.mdx @@ -26,7 +26,7 @@ Clarity's bit manipulation functions are designed with several important conside (bit-and i1 i2...) ``` -**Best Practices**: +**Best practices**: - Use to check if a specific flag is set in a bitfield. - Combine with bit-or for more complex flag manipulations. @@ -55,7 +55,7 @@ Clarity's bit manipulation functions are designed with several important conside (bit-or i1 i2...) ``` -**Best Practices**: +**Best practices**: - Use to add new permissions or flags to an existing set. - Combine with bit-and for more complex flag manipulations. @@ -79,7 +79,7 @@ Clarity's bit manipulation functions are designed with several important conside (bit-not i1) ``` -**Best Practices**: +**Best practices**: - Use carefully with signed integers, as it affects the sign bit. - Combine with bit-and to clear specific bits. @@ -93,7 +93,7 @@ Clarity's bit manipulation functions are designed with several important conside (remove-permission u7 PERMISSION_WRITE) ;; Returns (ok u5) ``` -## Practical Example: Compact User Profile Flags +## Practical example: Compact user profile flags Let's implement a system that stores multiple user profile settings in a single integer using bit flags: diff --git a/content/docs/stacks/clarity/cryptographic-functions.mdx b/content/docs/stacks/clarity/cryptographic-functions.mdx index 600de27b..1a42632e 100644 --- a/content/docs/stacks/clarity/cryptographic-functions.mdx +++ b/content/docs/stacks/clarity/cryptographic-functions.mdx @@ -26,7 +26,7 @@ Clarity's cryptographic functions are designed with blockchain-specific consider ```clarity (sha256 value) ``` -**Best Practices**: +**Best practices**: - Use for creating unique identifiers for data - Combine with other data before hashing to prevent rainbow table attacks @@ -48,7 +48,7 @@ Clarity's cryptographic functions are designed with blockchain-specific consider ```clarity (keccak256 value) ``` -**Best Practices**: +**Best practices**: - Use when SHA256 is not suitable for your specific use case - Be aware of the differences in output compared to SHA256 @@ -69,7 +69,7 @@ Clarity's cryptographic functions are designed with blockchain-specific consider ```clarity (secp256k1-recover? message-hash signature) ``` -**Best Practices**: +**Best practices**: - Always check the return value as it's an optional type - Use in combination with `secp256k1-verify` for complete signature verification @@ -82,7 +82,7 @@ Clarity's cryptographic functions are designed with blockchain-specific consider (map-set votes tx-sender vote) (ok true))) -## Practical Example: Document Verification System +## Practical example: Document verification system Let's implement a basic document verification system that demonstrates the use of Clarity's cryptographic functions. This system will allow users to submit document hashes, sign them, and later verify the authenticity of the document and the signer. diff --git a/content/docs/stacks/clarity/functions/add.mdx b/content/docs/stacks/clarity/functions/add.mdx index b438f459..9d347f28 100644 --- a/content/docs/stacks/clarity/functions/add.mdx +++ b/content/docs/stacks/clarity/functions/add.mdx @@ -5,7 +5,7 @@ description: Using the addition function for arithmetic operations in Clarity sm The addition function (`+`) in Clarity performs addition on a variable number of integer inputs. It's a fundamental arithmetic operation used in many smart contract calculations. -## Function Signature +## Function signature ```clarity (+ i1 i2...) @@ -32,14 +32,14 @@ Use the addition function when you need to: - Sum up multiple values. - Implement mathematical formulas that involve addition. -## Best Practices +## Best practices - Always consider the possibility of overflow when adding large numbers. - Use appropriate types (int or uint) based on your needs and expected value ranges. - Be aware that adding negative numbers to positive numbers can result in subtraction. - Consider using checked arithmetic functions if overflow detection is critical. -## Practical Example: Simple Counter +## Practical example: Simple counter Let's implement a simple counter that uses the addition function to increment its value: @@ -63,13 +63,13 @@ This example demonstrates: 2. Implementing a public function to handle the increment operation. 3. Returning the updated counter value. -## Common Pitfalls +## Common pitfalls 1. Overlooking potential overflow when adding large numbers. 2. Not considering the effect of adding negative numbers (for int types). 3. Forgetting to update related variables or state when incrementing values. -## Related Functions +## Related functions - `-`: Used for subtraction operations. - `*`: Used for multiplication operations. diff --git a/content/docs/stacks/clarity/functions/and.mdx b/content/docs/stacks/clarity/functions/and.mdx index 8471ee30..4e8b67cd 100644 --- a/content/docs/stacks/clarity/functions/and.mdx +++ b/content/docs/stacks/clarity/functions/and.mdx @@ -5,7 +5,7 @@ description: Using the and function for logical operations in Clarity smart cont The `and` function in Clarity performs a logical AND operation on two or more boolean inputs. It's a fundamental logical operation used in many smart contract conditions and control flows. -## Function Signature +## Function signature ```clarity (and b1 b2 ...) @@ -32,14 +32,14 @@ Use the `and` function when you need to: - Optimize condition checking by short-circuiting. - Combine the results of multiple comparison operations. -## Best Practices +## Best practices - Leverage the short-circuiting behavior for efficiency. - Order conditions from most likely to fail to least likely for better performance. - Use parentheses to group complex logical expressions for clarity. - Consider breaking very complex `and` expressions into separate functions or variables for readability. -## Practical Example: Simple Access Control +## Practical example: Simple access control Let's implement a simple access control function that uses the `and` function to check multiple conditions: @@ -74,13 +74,13 @@ This example demonstrates: 2. Combining multiple conditions in a single `and` expression. 3. Leveraging short-circuiting to avoid unnecessary computations if the first condition fails. -## Common Pitfalls +## Common pitfalls 1. Forgetting that `and` short-circuits, which might lead to unexpected behavior if side effects are intended in later conditions. 2. Over-complicating logical expressions, making them hard to read and maintain. 3. Not considering the order of conditions for optimal performance. -## Related Functions +## Related functions - `or`: Used for logical OR operations. - `not`: Used to negate boolean values. diff --git a/content/docs/stacks/clarity/functions/append.mdx b/content/docs/stacks/clarity/functions/append.mdx index 1a3e479a..9771915c 100644 --- a/content/docs/stacks/clarity/functions/append.mdx +++ b/content/docs/stacks/clarity/functions/append.mdx @@ -3,7 +3,7 @@ title: append description: Using the append function to add elements to lists in Clarity smart contracts, with considerations for maximum list length. --- -## Function Signature +## Function signature ```clarity (append (list A) A) @@ -30,7 +30,7 @@ Use the `append` function when you need to: - Implement data structures that require adding elements in order. - Combine existing lists with single elements. -## Best Practices +## Best practices - Always use `as-max-len?` before appending to ensure the list doesn't exceed its maximum length. - Be mindful of the maximum list length specified when defining the list. @@ -38,7 +38,7 @@ Use the `append` function when you need to: - Remember that `append` creates a new list; it doesn't modify the original list in-place. - Use type-appropriate elements that match the list's declared type. -## Practical Example: Event Log with Max Length Check +## Practical example: Event log with max length check Let's implement a simple event log system using `append` with a maximum length check: @@ -73,14 +73,14 @@ This example demonstrates: 3. Handling the case where the list would exceed its maximum length. 4. Combining `append` with other Clarity functions like `var-set` and `var-get`. -## Common Pitfalls +## Common pitfalls 1. Forgetting to use `as-max-len?` when appending to a list with a maximum length. 2. Attempting to append an element of the wrong type to a typed list. 3. Assuming `append` will always succeed without checking the list's current length. 4. Inefficiently using `append` in a loop when `concat` might be more appropriate. -## Related Functions +## Related functions - `as-max-len?`: Used to check if a sequence exceeds a maximum length. - `concat`: Used for joining two lists together. diff --git a/content/docs/stacks/clarity/functions/as-contract.mdx b/content/docs/stacks/clarity/functions/as-contract.mdx index 373539ca..fa6d1848 100644 --- a/content/docs/stacks/clarity/functions/as-contract.mdx +++ b/content/docs/stacks/clarity/functions/as-contract.mdx @@ -3,7 +3,7 @@ title: as-contract description: Using the as-contract function to execute expressions as the contract principal in Clarity smart contracts. --- -## Function Signature +## Function signature ```clarity (as-contract expr) @@ -30,14 +30,14 @@ Use the `as-contract` function when you need to: - Execute privileged operations that should only be done by the contract itself. - Implement contract-owned resources or escrow-like functionality. -## Best Practices +## Best practices - Use `as-contract` sparingly and only when necessary to minimize potential security risks. - Ensure that the logic leading to `as-contract` calls is properly secured and access-controlled. - Be aware that `as-contract` changes the `tx-sender` context for the duration of the expression. - Combine `as-contract` with other security measures like `contract-caller` checks for robust security. -## Practical Example: Contract-Managed Treasury +## Practical example: Contract managed treasury Let's implement a simple treasury system where the contract can distribute funds: @@ -69,13 +69,13 @@ This example demonstrates: 2. Using `as-contract` in the `withdraw` function to send funds from the contract's balance. 3. Combining `as-contract` with access control (`is-eq tx-sender CONTRACT_OWNER`) for security. -## Common Pitfalls +## Common pitfalls 1. Using `as-contract` unnecessarily, which can lead to unexpected behavior. 2. Forgetting that `as-contract` changes the `tx-sender` context, potentially affecting other parts of the code. 3. Not implementing proper access controls around `as-contract` calls, which could lead to unauthorized actions. -## Related Functions +## Related functions - `contract-caller`: Used to get the original caller of a contract function. - `tx-sender`: Represents the current sender (changes within `as-contract`). diff --git a/content/docs/stacks/clarity/functions/as-max-len.mdx b/content/docs/stacks/clarity/functions/as-max-len.mdx index 13642ce8..2cf94032 100644 --- a/content/docs/stacks/clarity/functions/as-max-len.mdx +++ b/content/docs/stacks/clarity/functions/as-max-len.mdx @@ -3,7 +3,7 @@ title: as-max-len? description: Using the as-max-len? function to check and limit sequence lengths in Clarity smart contracts. --- -## Function Signature +## Function signature ```clarity (as-max-len? sequence max_length) @@ -32,14 +32,14 @@ Use the `as-max-len?` function when you need to: - Validate user input or data from external sources. - Implement logic that depends on sequence length constraints. -## Best Practices +## Best practices - Always use `as-max-len?` before appending to lists or other sequences with maximum lengths. - Combine with `unwrap!` or `unwrap-panic` when you're certain the length should be within limits. - Use meaningful error handling when the length check fails. - Consider the performance impact of frequent length checks in your contract logic. -## Practical Example: Safe List Append +## Practical example: Safe list append Let's implement a function that safely appends to a list with a maximum length: @@ -75,13 +75,13 @@ This example demonstrates: 2. Combining `as-max-len?` with `unwrap!` for concise error handling. 3. Safely updating a list variable only if the length check passes. -## Common Pitfalls +## Common pitfalls 1. Forgetting to use `as-max-len?` when appending to sequences with maximum lengths. 2. Using a variable for the `max_length` parameter, which is not allowed (it must be a uint literal). 3. Not handling the `none` case when `as-max-len?` returns an optional. -## Related Functions +## Related functions - `append`: Used to add elements to lists. - `concat`: Used to join two sequences together. diff --git a/content/docs/stacks/clarity/functions/asserts.mdx b/content/docs/stacks/clarity/functions/asserts.mdx index 4938e2a1..468d6f83 100644 --- a/content/docs/stacks/clarity/functions/asserts.mdx +++ b/content/docs/stacks/clarity/functions/asserts.mdx @@ -3,7 +3,7 @@ title: asserts! description: Using the asserts! function for conditional assertions in Clarity smart contracts. --- -## Function Signature +## Function signature ```clarity (asserts! bool-expr thrown-value) @@ -32,14 +32,14 @@ Use the `asserts!` function when you need to: - Provide clear error messages or codes when conditions are not satisfied. - Implement guard clauses to protect against invalid inputs or states. -## Best Practices +## Best practices - Use `asserts!` early in functions to validate preconditions. - Provide meaningful error values that can be easily interpreted by users or other contracts. - Combine multiple conditions using `and` or `or` for complex assertions. - Consider using `asserts!` in combination with `unwrap!` for handling optional values. -## Practical Example: Token Transfer with Balance Check +## Practical example: Token transfer with balance check Let's implement a simple token transfer function that uses `asserts!` to check the sender's balance: @@ -73,13 +73,13 @@ This example demonstrates: 2. Using `asserts!` to prevent sending tokens to oneself. 3. Providing different error codes for different types of failures. -## Common Pitfalls +## Common pitfalls 1. Forgetting to handle the error case when calling functions that use `asserts!`. 2. Using `asserts!` excessively, which can make code harder to read and maintain. 3. Providing vague or unhelpful error values when assertions fail. -## Related Functions +## Related functions - `unwrap!`: Used to extract values from optionals with a fallback error. - `unwrap-panic`: Similar to `unwrap!` but causes a panic instead of returning an error. diff --git a/content/docs/stacks/clarity/functions/at-block.mdx b/content/docs/stacks/clarity/functions/at-block.mdx index 74bb3624..a136fe01 100644 --- a/content/docs/stacks/clarity/functions/at-block.mdx +++ b/content/docs/stacks/clarity/functions/at-block.mdx @@ -3,7 +3,7 @@ title: at-block description: Using the at-block function to evaluate expressions at a specific block in Clarity smart contracts. --- -## Function Signature +## Function signature ```clarity (at-block id-block-hash expr) @@ -33,14 +33,14 @@ Use the `at-block` function when you need to: - Verify past conditions without relying on stored state. - Create time-locked or checkpoint-based features in your contract. -## Best Practices +## Best practices - Only use `at-block` when historical data is necessary, as it can be computationally expensive. - Ensure the block hash used is from the `id-header-hash` property, not `header-hash`. - Use read-only expressions within `at-block` to maintain determinism. - Be aware of the potential for chain reorganizations when using recent block hashes. -## Practical Example: Historical Price Check +## Practical example: Historical price check Let's implement a simple function that checks if a price was above a certain threshold at a specific block: @@ -74,13 +74,13 @@ This example demonstrates: 2. Combining `at-block` with map lookups to access past state. 3. Implementing a read-only function that depends on blockchain history. -## Common Pitfalls +## Common pitfalls 1. Using `header-hash` instead of `id-header-hash`, which can lead to inconsistencies across forks. 2. Attempting to modify state within an `at-block` expression, which is not allowed. 3. Overusing `at-block`, which can lead to performance issues due to the cost of historical lookups. -## Related Functions +## Related functions - `get-block-info?`: Used to retrieve information about specific blocks. - `block-height`: Often used in conjunction with `at-block` for time-based logic. diff --git a/content/docs/stacks/clarity/functions/begin.mdx b/content/docs/stacks/clarity/functions/begin.mdx index 3c52bbe5..db8cc337 100644 --- a/content/docs/stacks/clarity/functions/begin.mdx +++ b/content/docs/stacks/clarity/functions/begin.mdx @@ -3,7 +3,7 @@ title: begin description: Using the begin function to evaluate multiple expressions in sequence in Clarity smart contracts. --- -## Function Signature +## Function signature ```clarity (begin expr1 expr2 expr3 ... expr-last) @@ -31,14 +31,14 @@ Use the `begin` function when you need to: - Group multiple expressions where only one is allowed (e.g., in function bodies or condition branches). - Create more complex, multi-step logic within your smart contract functions. -## Best Practices +## Best practices - Use `begin` to keep related operations together for better readability. - Ensure that any expressions that return a response type (ok or err) are properly checked. - Be mindful of the order of expressions, as they are evaluated sequentially. - Use `begin` to make your code more expressive and easier to understand. -## Practical Example: User Registration with Logging +## Practical example: User registration with logging Let's implement a simple user registration function that performs multiple actions: @@ -66,13 +66,13 @@ This example demonstrates: 2. Performing checks, updates, and logging in a specific order. 3. Executing side effects (printing) before returning the final value. -## Common Pitfalls +## Common pitfalls 1. Forgetting to return a value in the last expression of a `begin` block. 2. Not properly handling responses from functions that return (ok) or (err) within the `begin` block. 3. Relying on side effects of earlier expressions without considering their order of execution. -## Related Functions +## Related functions - `let`: Used for creating local bindings within a limited scope. - `asserts!`: Often used within `begin` blocks for condition checking. diff --git a/content/docs/stacks/clarity/functions/bit-and.mdx b/content/docs/stacks/clarity/functions/bit-and.mdx index 9e67c400..c51c2e78 100644 --- a/content/docs/stacks/clarity/functions/bit-and.mdx +++ b/content/docs/stacks/clarity/functions/bit-and.mdx @@ -5,7 +5,7 @@ description: Using the bit-and function for bitwise operations in Clarity smart The `bit-and` function in Clarity performs a bitwise AND operation on two or more integer inputs. It's a powerful tool for working with compact data representations and flag systems in smart contracts. -## Function Signature +## Function signature ```clarity (bit-and i1 i2...) @@ -32,14 +32,14 @@ Use `bit-and` when you need to: - Clear specific bits while leaving others unchanged - Perform certain low-level optimizations -## Best Practices +## Best practices - Always use constants for bit flags to improve readability and maintainability. - Be cautious when using with signed integers, as the sign bit can affect results. - Combine with other bitwise operations like `bit-or` and `bit-not` for more complex manipulations. - Document your bit flag meanings clearly in your contract. -## Practical Example: Role-Based Access Control +## Practical example: Role-based access control Let's implement a simple role-based access control system using `bit-and`: @@ -89,13 +89,13 @@ This example demonstrates: 2. Combining `bit-and` with `bit-or` and `bit-not` for role management. 3. Efficient storage of multiple roles in a single integer. -## Common Pitfalls +## Common pitfalls 1. Forgetting that `bit-and` with 0 always results in 0. 2. Not accounting for the sign bit when using signed integers. 3. Overcomplicating bit flag systems, making them hard to maintain. -## Related Functions +## Related functions - `bit-or`: Used to set bits or combine flags. - `bit-not`: Used to invert bits, often in combination with `bit-and` for clearing specific bits. diff --git a/content/docs/stacks/clarity/functions/bit-not.mdx b/content/docs/stacks/clarity/functions/bit-not.mdx index b607173c..74087ec7 100644 --- a/content/docs/stacks/clarity/functions/bit-not.mdx +++ b/content/docs/stacks/clarity/functions/bit-not.mdx @@ -3,7 +3,7 @@ title: bit-not description: Using the bit-not function for bitwise complement operations in Clarity smart contracts. --- -## Function Signature +## Function signature ```clarity (bit-not i1) @@ -30,14 +30,14 @@ Use the `bit-not` function when you need to: - Implement certain cryptographic or hashing algorithms. - Perform low-level data manipulations. -## Best Practices +## Best practices - Be aware of the differences between signed (`int`) and unsigned (`uint`) integers when using `bit-not`. - Remember that `bit-not` on a `uint` will result in a large positive number due to two's complement representation. - Use `bit-not` in combination with other bitwise operations (`bit-and`, `bit-or`, `bit-xor`) for complex bit manipulations. - Consider the readability of your code when using bitwise operations extensively. -## Practical Example: Simple Flag System +## Practical example: Simple flag system Let's implement a simple flag system using `bit-not` and other bitwise operations: @@ -71,13 +71,13 @@ This example demonstrates: 2. Implementing a flag system using bitwise operations for efficient storage and manipulation. 3. Combining `bit-not` with other bitwise operations for complex flag manipulations. -## Common Pitfalls +## Common pitfalls 1. Forgetting that `bit-not` on a `uint` results in a large positive number, not a negative number. 2. Overlooking the sign bit when using `bit-not` with signed integers. 3. Not considering the full range of bits when applying `bit-not` to smaller integer values. -## Related Functions +## Related functions - `bit-and`: Used for bitwise AND operations. - `bit-or`: Used for bitwise OR operations. diff --git a/content/docs/stacks/clarity/functions/bit-or.mdx b/content/docs/stacks/clarity/functions/bit-or.mdx index e9de9f2b..5858348d 100644 --- a/content/docs/stacks/clarity/functions/bit-or.mdx +++ b/content/docs/stacks/clarity/functions/bit-or.mdx @@ -3,7 +3,7 @@ title: bit-or description: Using the bit-or function for bitwise OR operations in Clarity smart contracts. --- -## Function Signature +## Function signature ```clarity (bit-or i1 i2...) @@ -30,14 +30,14 @@ Use the `bit-or` function when you need to: - Implement certain bitwise algorithms or data structures. - Perform low-level data manipulations involving binary operations. -## Best Practices +## Best practices - Ensure all input values are of the same type (either all `int` or all `uint`). - Remember that `bit-or` with `0` has no effect, which can be useful for conditional operations. - Use `bit-or` in combination with other bitwise operations for complex bit manipulations. - Consider readability when using bitwise operations extensively; add comments to explain the purpose. -## Practical Example: Permission System +## Practical example: Permission system Let's implement a simple permission system using `bit-or` and other bitwise operations: @@ -89,13 +89,13 @@ This example demonstrates: 2. Implementing a permission system using bitwise operations for efficient storage and checks. 3. Combining `bit-or` with other bitwise operations like `bit-and` and `bit-not` for complex permission management. -## Common Pitfalls +## Common pitfalls 1. Mixing signed (`int`) and unsigned (`uint`) integers in a single `bit-or` operation. 2. Forgetting that `bit-or` with all bits set (`-1` for `int`, maximum value for `uint`) always results in all bits set. 3. Not considering the full range of bits when using `bit-or` with smaller integer values. -## Related Functions +## Related functions - `bit-and`: Used for bitwise AND operations. - `bit-xor`: Used for bitwise XOR operations. diff --git a/content/docs/stacks/clarity/functions/bit-shift-left.mdx b/content/docs/stacks/clarity/functions/bit-shift-left.mdx index 8bd4007f..104fba91 100644 --- a/content/docs/stacks/clarity/functions/bit-shift-left.mdx +++ b/content/docs/stacks/clarity/functions/bit-shift-left.mdx @@ -3,7 +3,7 @@ title: bit-shift-left description: Using the bit-shift-left function for bitwise left shift operations in Clarity smart contracts. --- -## Function Signature +## Function signature ```clarity (bit-shift-left i1 shamt) @@ -32,14 +32,14 @@ Use the `bit-shift-left` function when you need to: - Create specific bit patterns or masks. - Optimize certain bitwise operations. -## Best Practices +## Best practices - Remember that shifting beyond the bit width of the integer (128 bits in Clarity) will result in zero. - Use `uint` for `shamt` to avoid potential issues with negative shift amounts. - Be aware of the potential for overflow when shifting left, especially with large numbers or shift amounts. - For multiplication by powers of 2, use the `pow` function instead, as it provides built-in overflow protection. -## Practical Example: Flag Management +## Practical example: Flag management Let's implement a simple flag management system using `bit-shift-left`: @@ -71,13 +71,13 @@ This example demonstrates: 2. Combining `bit-shift-left` with `bit-or` to set flags. 3. Using `bit-and` to check if a specific flag is set. -## Common Pitfalls +## Common pitfalls 1. Using `bit-shift-left` for multiplication without considering overflow risks. 2. Not considering the modulo behavior when shifting by amounts greater than or equal to 128. 3. Using a negative or non-uint value for the shift amount, which is not allowed. -## Related Functions +## Related functions - `bit-shift-right`: Used for right-shifting bits. - `bit-and`: Often used in combination with `bit-shift-left` for masking operations. diff --git a/content/docs/stacks/clarity/functions/bit-shift-right.mdx b/content/docs/stacks/clarity/functions/bit-shift-right.mdx index 37351b19..c989e58f 100644 --- a/content/docs/stacks/clarity/functions/bit-shift-right.mdx +++ b/content/docs/stacks/clarity/functions/bit-shift-right.mdx @@ -3,7 +3,7 @@ title: bit-shift-right description: Using the bit-shift-right function for bitwise right shift operations in Clarity smart contracts. --- -## Function Signature +## Function signature ```clarity (bit-shift-right i1 shamt) @@ -32,14 +32,14 @@ Use the `bit-shift-right` function when you need to: - Perform low-level data manipulations involving binary operations. - Extract specific bits or bit patterns from integers. -## Best Practices +## Best practices - Be aware that shifting right by `n` bits is equivalent to integer division by 2^n. - Remember that for signed integers (`int`), the sign bit is preserved during right shifts. - Use `uint` for `shamt` to avoid potential issues with negative shift amounts. - Consider the differences in behavior between signed and unsigned integers when right-shifting. -## Practical Example: Efficient Power of 2 Division +## Practical example: Power of 2 division Let's implement a function that efficiently divides by powers of 2 using `bit-shift-right`: @@ -63,13 +63,13 @@ This example demonstrates: 2. Handling both positive and negative numbers in division. 3. Combining `bit-shift-right` with other bitwise operations to extract specific bit patterns. -## Common Pitfalls +## Common pitfalls 1. Forgetting that right-shifting signed integers preserves the sign bit. 2. Not considering the modulo behavior when shifting by amounts greater than or equal to 128. 3. Using a negative or non-uint value for the shift amount, which is not allowed. -## Related Functions +## Related functions - `bit-shift-left`: Used for left-shifting bits. - `bit-and`: Often used in combination with `bit-shift-right` for masking operations. diff --git a/content/docs/stacks/clarity/functions/bit-xor.mdx b/content/docs/stacks/clarity/functions/bit-xor.mdx index 5cb797b4..3894017c 100644 --- a/content/docs/stacks/clarity/functions/bit-xor.mdx +++ b/content/docs/stacks/clarity/functions/bit-xor.mdx @@ -3,7 +3,7 @@ title: bit-xor description: Using the bit-xor function for bitwise exclusive OR operations in Clarity smart contracts. --- -## Function Signature +## Function signature ```clarity (bit-xor i1 i2...) @@ -30,14 +30,14 @@ Use the `bit-xor` function when you need to: - Compare two bit patterns to find differences. - Create simple encryption or hashing mechanisms. -## Best Practices +## Best practices - Ensure all input values are of the same type (either all `int` or all `uint`). - Remember that `bit-xor` with 0 returns the original value, which can be useful for conditional operations. - Use `bit-xor` in combination with other bitwise operations for complex bit manipulations. - Consider the readability of your code when using bitwise operations extensively; add comments to explain the purpose. -## Practical Example: Simple Toggle Mechanism +## Practical example: Simple toggle mechanism Let's implement a simple toggle mechanism using `bit-xor`: @@ -67,13 +67,13 @@ This example demonstrates: 2. Combining `bit-xor` with other bitwise operations like `bit-and` and `bit-shift-left`. 3. Implementing a simple flag system using bitwise operations for efficient storage and manipulation. -## Common Pitfalls +## Common pitfalls 1. Mixing signed (`int`) and unsigned (`uint`) integers in a single `bit-xor` operation. 2. Forgetting that `bit-xor` of a value with itself always results in 0. 3. Not considering the full range of bits when using `bit-xor` with smaller integer values. -## Related Functions +## Related functions - `bit-and`: Used for bitwise AND operations. - `bit-or`: Used for bitwise OR operations. diff --git a/content/docs/stacks/clarity/functions/buff-to-int-be.mdx b/content/docs/stacks/clarity/functions/buff-to-int-be.mdx index b42fb92f..dc1bd125 100644 --- a/content/docs/stacks/clarity/functions/buff-to-int-be.mdx +++ b/content/docs/stacks/clarity/functions/buff-to-int-be.mdx @@ -3,7 +3,7 @@ title: buff-to-int-be description: Converting a byte buffer to a signed integer using big-endian encoding in Clarity smart contracts. --- -## Function Signature +## Function signature ```clarity (buff-to-int-be (buff 16)) @@ -30,14 +30,14 @@ Use the `buff-to-int-be` function when you need to: - Implement cryptographic or mathematical operations that expect big-endian integer inputs. - Ensure compatibility with external systems using big-endian encoding. -## Best Practices +## Best practices - Ensure the input buffer is no larger than 16 bytes to avoid errors. - Be aware that smaller buffers are zero-padded on the left, affecting the resulting integer value. - Consider using `buff-to-uint-be` for unsigned integers if the sign is not needed. - Handle potential errors when the input buffer might be invalid or empty. -## Practical Example: Decoding a Signed Integer from External Data +## Practical example: Decode a signed integer from external data Let's implement a function that processes external data containing a big-endian encoded signed integer: @@ -65,13 +65,13 @@ This example demonstrates: 2. Handling both positive and negative values resulting from the conversion. 3. Implementing input validation based on the converted integer value. -## Common Pitfalls +## Common pitfalls 1. Forgetting that the function interprets the input as big-endian, which might lead to unexpected values if the data is actually little-endian. 2. Not handling potential negative values when working with signed integers. 3. Assuming a specific buffer length, which could lead to unexpected results with shorter inputs due to left-padding. -## Related Functions +## Related functions - `buff-to-int-le`: Converts a byte buffer to a signed integer using little-endian encoding. - `buff-to-uint-be`: Converts a byte buffer to an unsigned integer using big-endian encoding. diff --git a/content/docs/stacks/clarity/functions/buff-to-int-le.mdx b/content/docs/stacks/clarity/functions/buff-to-int-le.mdx index 0ccd47f8..66cd33ba 100644 --- a/content/docs/stacks/clarity/functions/buff-to-int-le.mdx +++ b/content/docs/stacks/clarity/functions/buff-to-int-le.mdx @@ -3,7 +3,7 @@ title: buff-to-int-le description: Converting a byte buffer to a signed integer using little-endian encoding in Clarity smart contracts. --- -## Function Signature +## Function signature ```clarity (buff-to-int-le (buff 16)) @@ -30,14 +30,14 @@ Use the `buff-to-int-le` function when you need to: - Implement cryptographic or mathematical operations that expect little-endian integer inputs. - Ensure compatibility with external systems using little-endian encoding. -## Best Practices +## Best practices - Ensure the input buffer is no larger than 16 bytes to avoid errors. - Be aware that smaller buffers are zero-padded on the right, affecting the resulting integer value. - Consider using `buff-to-uint-le` for unsigned integers if the sign is not needed. - Handle potential errors when the input buffer might be invalid or empty. -## Practical Example: Decoding a Signed Integer from External Data +## Practical example: Decode a signed integer from external data Let's implement a function that processes external data containing a little-endian encoded signed integer: @@ -65,13 +65,13 @@ This example demonstrates: 2. Handling both positive and negative values resulting from the conversion. 3. Implementing input validation based on the converted integer value. -## Common Pitfalls +## Common pitfalls 1. Confusing little-endian with big-endian encoding, leading to incorrect integer values. 2. Not handling potential negative values when working with signed integers. 3. Assuming a specific buffer length, which could lead to unexpected results with shorter inputs due to right-padding. -## Related Functions +## Related functions - `buff-to-int-be`: Converts a byte buffer to a signed integer using big-endian encoding. - `buff-to-uint-le`: Converts a byte buffer to an unsigned integer using little-endian encoding. diff --git a/content/docs/stacks/clarity/functions/buff-to-uint-be.mdx b/content/docs/stacks/clarity/functions/buff-to-uint-be.mdx index 03ea8e45..08eb456f 100644 --- a/content/docs/stacks/clarity/functions/buff-to-uint-be.mdx +++ b/content/docs/stacks/clarity/functions/buff-to-uint-be.mdx @@ -3,7 +3,7 @@ title: buff-to-uint-be description: Converting a byte buffer to an unsigned integer using big-endian encoding in Clarity smart contracts. --- -## Function Signature +## Function signature ```clarity (buff-to-uint-be (buff 16)) @@ -30,14 +30,14 @@ Use the `buff-to-uint-be` function when you need to: - Implement cryptographic or mathematical operations that expect big-endian integer inputs. - Ensure compatibility with external systems using big-endian encoding. -## Best Practices +## Best practices - Ensure the input buffer is no larger than 16 bytes to avoid errors. - Be aware that smaller buffers are zero-padded on the left, affecting the resulting integer value. - Use `buff-to-int-be` if you need to handle signed integers instead. - Handle potential errors when the input buffer might be invalid or empty. -## Practical Example: Decoding an Unsigned Integer from External Data +## Practical example: Decode an unsigned integer from external data Let's implement a function that processes external data containing a big-endian encoded unsigned integer: @@ -65,13 +65,13 @@ This example demonstrates: 2. Implementing input validation based on the converted integer value. 3. Handling different input sizes and values. -## Common Pitfalls +## Common pitfalls 1. Forgetting that the function interprets the input as big-endian, which might lead to unexpected values if the data is actually little-endian. 2. Not considering the full range of possible uint values when processing the result. 3. Assuming a specific buffer length, which could lead to unexpected results with shorter inputs due to left-padding. -## Related Functions +## Related functions - `buff-to-uint-le`: Converts a byte buffer to an unsigned integer using little-endian encoding. - `buff-to-int-be`: Converts a byte buffer to a signed integer using big-endian encoding. diff --git a/content/docs/stacks/clarity/functions/buff-to-uint-le.mdx b/content/docs/stacks/clarity/functions/buff-to-uint-le.mdx index 5dcef766..32ba2aaa 100644 --- a/content/docs/stacks/clarity/functions/buff-to-uint-le.mdx +++ b/content/docs/stacks/clarity/functions/buff-to-uint-le.mdx @@ -3,7 +3,7 @@ title: buff-to-uint-le description: Converting a byte buffer to an unsigned integer using little-endian encoding in Clarity smart contracts. --- -## Function Signature +## Function signature ```clarity (buff-to-uint-le (buff 16)) @@ -30,14 +30,14 @@ Use the `buff-to-uint-le` function when you need to: - Implement cryptographic or mathematical operations that expect little-endian integer inputs. - Ensure compatibility with external systems using little-endian encoding. -## Best Practices +## Best practices - Ensure the input buffer is no larger than 16 bytes to avoid errors. - Be aware that smaller buffers are zero-padded on the right, affecting the resulting integer value. - Use `buff-to-int-le` if you need to handle signed integers instead. - Handle potential errors when the input buffer might be invalid or empty. -## Practical Example: Decoding an Unsigned Integer from External Data +## Practical example: Decode an unsigned integer from external data Let's implement a function that processes external data containing a little-endian encoded unsigned integer: @@ -65,13 +65,13 @@ This example demonstrates: 2. Implementing input validation based on the converted integer value. 3. Handling different input sizes and values. -## Common Pitfalls +## Common pitfalls 1. Confusing little-endian with big-endian encoding, leading to incorrect integer values. 2. Not considering the full range of possible uint values when processing the result. 3. Assuming a specific buffer length, which could lead to unexpected results with shorter inputs due to right-padding. -## Related Functions +## Related functions - `buff-to-uint-be`: Converts a byte buffer to an unsigned integer using big-endian encoding. - `buff-to-int-le`: Converts a byte buffer to a signed integer using little-endian encoding. diff --git a/content/docs/stacks/clarity/functions/concat.mdx b/content/docs/stacks/clarity/functions/concat.mdx index 79717515..63e6d8d1 100644 --- a/content/docs/stacks/clarity/functions/concat.mdx +++ b/content/docs/stacks/clarity/functions/concat.mdx @@ -3,7 +3,7 @@ title: concat description: Concatenating sequences in Clarity smart contracts. --- -## Function Signature +## Function signature ```clarity (concat sequence1 sequence2) @@ -30,14 +30,14 @@ Use the `concat` function when you need to: - Merge two lists into a single list. - Build complex data structures from simpler components. -## Best Practices +## Best practices - Ensure that both input sequences are of the same type (e.g., both strings, both buffers, or both lists). - Be aware of the maximum length limitations for the resulting sequence type. - Consider using `concat` in combination with other sequence manipulation functions for more complex operations. - When working with strings, remember that Clarity distinguishes between ASCII and UTF-8 strings. -## Practical Example: Dynamic Message Construction +## Practical example: Dynamic message construction Let's implement a function that constructs a personalized message: @@ -55,13 +55,13 @@ This example demonstrates: 2. Nesting `concat` calls to build a more complex string. 3. Combining static and dynamic parts of a message. -## Common Pitfalls +## Common pitfalls 1. Attempting to concatenate sequences of different types, which will result in an error. 2. Not considering the maximum length of the resulting sequence, potentially leading to truncation. 3. Forgetting that `concat` only works with two sequences at a time, requiring nested calls for multiple concatenations. -## Related Functions +## Related functions - `len`: Used to get the length of a sequence. - `slice?`: Can be used to extract parts of a sequence before concatenation. diff --git a/content/docs/stacks/clarity/functions/contract-call.mdx b/content/docs/stacks/clarity/functions/contract-call.mdx index 11721aff..bc14bf5d 100644 --- a/content/docs/stacks/clarity/functions/contract-call.mdx +++ b/content/docs/stacks/clarity/functions/contract-call.mdx @@ -3,7 +3,7 @@ title: contract-call? description: Executing public functions in other smart contracts from within a Clarity smart contract. --- -## Function Signature +## Function signature ```clarity (contract-call? .contract-name function-name arg0 arg1 ...) @@ -33,14 +33,14 @@ Use the `contract-call?` function when you need to: - Split complex logic across multiple contracts for better organization. - Implement upgradeable systems by calling into newer contract versions. -## Best Practices +## Best practices - Always check the return value of `contract-call?` as it returns a response type. - Be aware that `contract-call?` cannot be used to call functions within the same contract. - Consider the gas costs of external contract calls in your overall transaction budget. - Use `as-contract` when appropriate to make calls with the contract's own principal. -## Practical Example: Interacting with a Token Contract +## Practical example: Interact with a token contract Let's implement a function that transfers tokens using a standard token contract: @@ -58,13 +58,13 @@ This example demonstrates: 2. Passing arguments to the called function, including the current `tx-sender`. 3. Returning the response from the called function directly. -## Common Pitfalls +## Common pitfalls 1. Forgetting to handle the response from `contract-call?`, which can lead to unexpected behavior. 2. Attempting to use `contract-call?` to call functions within the same contract, which is not allowed. 3. Not considering the possibility of the called contract changing or being upgraded. -## Related Functions +## Related functions - `as-contract`: Often used in combination with `contract-call?` to make calls as the contract principal. - `try!`: Useful for handling the response from `contract-call?` and propagating errors. diff --git a/content/docs/stacks/clarity/functions/contract-of.mdx b/content/docs/stacks/clarity/functions/contract-of.mdx index 1e604c55..7cb4769b 100644 --- a/content/docs/stacks/clarity/functions/contract-of.mdx +++ b/content/docs/stacks/clarity/functions/contract-of.mdx @@ -3,7 +3,7 @@ title: contract-of description: Retrieving the principal of a contract implementing a trait in Clarity smart contracts. --- -## Function Signature +## Function signature ```clarity (contract-of ) @@ -32,14 +32,14 @@ Use the `contract-of` function when you need to: - Manage routing logic between different versions of contracts for upgradeable smart contracts. - Implement access control mechanisms to restrict function calls to designated contracts. -## Best Practices +## Best practices - Use `contract-of` in combination with traits to create more flexible and composable smart contracts. - Remember that `contract-of` returns a principal, which can be used in other Clarity functions expecting a contract address. - Consider using `contract-of` when implementing proxy or router contracts that work with multiple similar contracts. - Be aware that `contract-of` can only be used with trait references, not with direct contract references. -## Practical Example: Modular Approach to Extension Contracts +## Practical example: Modular approach to extension contracts Let's implement a system where specific functions can only be called by designated extension contracts: @@ -111,13 +111,13 @@ This example demonstrates: 3. Restricting access to certain functions based on the authorized extension contracts. 4. Allowing the authorized extension contracts to call specific functions. -## Common Pitfalls +## Common pitfalls 1. Attempting to use `contract-of` with a direct contract reference instead of a trait reference. 2. Forgetting that `contract-of` returns a principal, not a contract reference itself. 3. Not handling potential errors when working with trait references that might not be properly initialized. -## Related Functions +## Related functions - `use-trait`: Used to define trait references that can be used with `contract-of`. - `contract-call?`: Often used in combination with `contract-of` to call functions on the retrieved contract. diff --git a/content/docs/stacks/clarity/functions/default-to.mdx b/content/docs/stacks/clarity/functions/default-to.mdx index 2a52667d..2d8e2a86 100644 --- a/content/docs/stacks/clarity/functions/default-to.mdx +++ b/content/docs/stacks/clarity/functions/default-to.mdx @@ -3,7 +3,7 @@ title: default-to description: Providing a default value for optional types in Clarity smart contracts. --- -## Function Signature +## Function signature ```clarity (default-to default-value option-value) @@ -32,14 +32,14 @@ Use the `default-to` function when you need to: - Set a fallback value for potentially missing data in your contract logic. - Simplify error handling for operations that might not return a value. -## Best Practices +## Best practices - Choose meaningful default values that make sense in the context of your contract logic. - Use `default-to` to make your code more concise and readable when dealing with optionals. - Consider the implications of using the default value in your contract's logic. - Combine `default-to` with other Clarity functions like `map-get?` for efficient data handling. -## Practical Example: User Profile Lookup +## Practical example: User profile lookup Let's implement a function that retrieves a user's profile information with default values: @@ -69,13 +69,13 @@ This example demonstrates: 2. Providing default values for individual fields within the profile. 3. Creating a safe way to retrieve user information without explicit null checks. -## Common Pitfalls +## Common pitfalls 1. Forgetting that `default-to` only works with optional types, not with general error handling. 2. Using default values that might be indistinguishable from valid data, leading to confusion. 3. Overusing `default-to` where explicit error handling might be more appropriate. -## Related Functions +## Related functions - `map-get?`: Often used in combination with `default-to` for safe map lookups. - `get`: Can return optional values that are then handled by `default-to`. diff --git a/content/docs/stacks/clarity/functions/define-constant.mdx b/content/docs/stacks/clarity/functions/define-constant.mdx index 15304941..962fcfa5 100644 --- a/content/docs/stacks/clarity/functions/define-constant.mdx +++ b/content/docs/stacks/clarity/functions/define-constant.mdx @@ -3,7 +3,7 @@ title: define-constant description: Defining immutable constants in Clarity smart contracts. --- -## Function Signature +## Function signature ```clarity (define-constant name expression) @@ -32,14 +32,14 @@ Use `define-constant` when you need to: - Declare contract-wide configuration parameters. - Optimize gas usage for values that are computed but never change. -## Best Practices +## Best practices - Use uppercase names for constants to distinguish them from variables. - Place constant definitions at the top of your contract for better visibility. - Use constants for values that are used multiple times in your contract. - Consider using constants for contract configuration that might need to change between deployments. -## Practical Example: Token Configuration +## Practical example: Token configuration Let's implement a simple token contract using constants for configuration: @@ -73,13 +73,13 @@ This example demonstrates: 2. Referencing these constants in various parts of the contract. 3. Improving readability and maintainability of the contract. -## Common Pitfalls +## Common pitfalls 1. Attempting to modify a constant after it's defined, which is not allowed. 2. Using `define-constant` for values that need to change during contract execution (use `define-data-var` instead). 3. Overusing constants for values used only once, which can decrease readability. -## Related Functions +## Related functions - `define-data-var`: Used for defining mutable variables. - `define-map`: Used for defining data maps. diff --git a/content/docs/stacks/clarity/functions/define-data-var.mdx b/content/docs/stacks/clarity/functions/define-data-var.mdx index d049c4d1..f6d9d1d2 100644 --- a/content/docs/stacks/clarity/functions/define-data-var.mdx +++ b/content/docs/stacks/clarity/functions/define-data-var.mdx @@ -3,7 +3,7 @@ title: define-data-var description: Defining mutable variables in Clarity smart contracts. --- -## Function Signature +## Function signature ```clarity (define-data-var name type value) @@ -33,14 +33,14 @@ Use `define-data-var` when you need to: - Store temporary or intermediate state that may be modified by contract functions. - Maintain configurable parameters that can be updated by authorized parties. -## Best Practices +## Best practices - Use `define-data-var` for values that need to change; for immutable values, use `define-constant` instead. - Initialize variables with meaningful default values. - Consider access control for functions that modify important data variables. - Use clear and descriptive names for your variables to enhance readability. -## Practical Example: Simple Counter +## Practical example: Simple counter Let's implement a basic counter using `define-data-var`: @@ -73,13 +73,13 @@ This example demonstrates: 3. Using `var-get` and `var-set` to read and modify the variable's value. 4. Adding a safety check to prevent the counter from becoming negative. -## Common Pitfalls +## Common pitfalls 1. Forgetting that `define-data-var` creates mutable state, which can lead to unexpected behavior if not managed carefully. 2. Not considering the initial value's impact on contract logic, especially if the contract relies on the variable's state. 3. Overusing mutable variables when constants or maps might be more appropriate for the use case. -## Related Functions +## Related functions - `var-get`: Used to retrieve the current value of a data variable. - `var-set`: Used to update the value of a data variable. diff --git a/content/docs/stacks/clarity/functions/define-fungible-token.mdx b/content/docs/stacks/clarity/functions/define-fungible-token.mdx index 98454680..a376cccd 100644 --- a/content/docs/stacks/clarity/functions/define-fungible-token.mdx +++ b/content/docs/stacks/clarity/functions/define-fungible-token.mdx @@ -3,7 +3,7 @@ title: define-fungible-token description: Defining a new fungible token in Clarity smart contracts. --- -## Function Signature +## Function signature ```clarity (define-fungible-token token-name ) @@ -32,14 +32,14 @@ Use `define-fungible-token` when you need to: - Establish a foundation for token-based features in your contract. - Create utility tokens, governance tokens, or other custom fungible assets. -## Best Practices +## Best practices - Place `define-fungible-token` at the top level of your contract, as it's a definition statement. - Consider carefully whether to specify a total supply or leave it unlimited. - Use meaningful and descriptive names for your tokens. - Implement proper access controls for minting and burning operations if required. -## Practical Example: Simple Token Creation +## Practical example: Simple token creation Let's implement a basic fungible token with a fixed supply: @@ -72,13 +72,13 @@ This example demonstrates: 2. Implementing basic token operations like transfer and balance checking. 3. Adding a mint function with admin-only access control. -## Common Pitfalls +## Common pitfalls 1. Forgetting that omitting the total supply parameter allows unlimited minting, if not handled manually. 2. Not implementing proper access controls for sensitive operations like minting. 3. Overlooking the need for additional functionality like burning or pausing. -## Related Functions +## Related functions - `ft-transfer?`: Used to transfer tokens between principals. - `ft-mint?`: Used to create new tokens (if allowed by the token definition). diff --git a/content/docs/stacks/clarity/functions/define-map.mdx b/content/docs/stacks/clarity/functions/define-map.mdx index 72d6b040..a3a61739 100644 --- a/content/docs/stacks/clarity/functions/define-map.mdx +++ b/content/docs/stacks/clarity/functions/define-map.mdx @@ -3,7 +3,7 @@ title: define-map description: Defining a data map in Clarity smart contracts. --- -## Function Signature +## Function signature ```clarity (define-map map-name key-type value-type) @@ -33,14 +33,14 @@ Use `define-map` when you need to: - Organize data that needs to be accessed by a specific identifier. - Create data structures that can be efficiently updated and queried. -## Best Practices +## Best practices - Choose appropriate types for keys and values to ensure efficient storage and retrieval. - Use meaningful names for your maps that reflect their purpose in the contract. - Consider using composite keys (tuples) for more complex data relationships. - Be mindful of the gas costs associated with map operations, especially for large datasets. -## Practical Example: Simple User Profile System +## Practical example: Simple user profile system Let's implement a basic user profile system using `define-map`: @@ -74,14 +74,14 @@ This example demonstrates: 3. Using map operations like `map-set`, `map-get?`, and `merge` to manipulate map data. 4. Handling cases where a profile might not exist using `default-to`. -## Common Pitfalls +## Common pitfalls 1. Forgetting that maps are not iterable in Clarity; you can't loop through all entries. 2. Not handling cases where a key might not exist in the map. 3. Overusing maps for data that might be better suited for other data structures. 4. Not considering the gas costs of map operations in complex contracts. -## Related Functions +## Related functions - `map-get?`: Used to retrieve a value from a map, returns an optional. - `map-set`: Used to set or update a value in a map. diff --git a/content/docs/stacks/clarity/functions/define-non-fungible-token.mdx b/content/docs/stacks/clarity/functions/define-non-fungible-token.mdx index 1e941a25..f789b4cb 100644 --- a/content/docs/stacks/clarity/functions/define-non-fungible-token.mdx +++ b/content/docs/stacks/clarity/functions/define-non-fungible-token.mdx @@ -3,7 +3,7 @@ title: define-non-fungible-token description: Defining a new non-fungible token class in Clarity smart contracts. --- -## Function Signature +## Function signature ```clarity (define-non-fungible-token asset-name asset-identifier-type) @@ -32,14 +32,14 @@ Use `define-non-fungible-token` when you need to: - Establish a foundation for NFT-based features in your contract. - Create collectibles, digital art tokens, or other unique digital assets. -## Best Practices +## Best practices - Place `define-non-fungible-token` at the top level of your contract, as it's a definition statement. - Choose an appropriate asset identifier type that ensures uniqueness for each token. - Use meaningful and descriptive names for your NFT classes. - Consider the scalability and gas costs associated with your chosen identifier type. -## Practical Example: Simple Digital Art NFT +## Practical example: Simple digital art NFT Let's implement a basic digital art NFT system: @@ -76,13 +76,13 @@ This example demonstrates: 2. Implementing basic NFT operations like minting, checking ownership, and transferring. 3. Using a simple incrementing integer as the token identifier. -## Common Pitfalls +## Common pitfalls 1. Forgetting that each token in an NFT class must have a unique identifier. 2. Not implementing proper access controls for minting and transferring operations. 3. Choosing an identifier type that may lead to collisions or scalability issues. -## Related Functions +## Related functions - `nft-mint?`: Used to create new tokens within the NFT class. - `nft-transfer?`: Used to transfer ownership of an NFT. diff --git a/content/docs/stacks/clarity/functions/define-private.mdx b/content/docs/stacks/clarity/functions/define-private.mdx index b8f74915..44a926e0 100644 --- a/content/docs/stacks/clarity/functions/define-private.mdx +++ b/content/docs/stacks/clarity/functions/define-private.mdx @@ -3,7 +3,7 @@ title: define-private description: Defining private functions in Clarity smart contracts. --- -## Function Signature +## Function signature ```clarity (define-private (function-name (arg-name-0 arg-type-0) ...) function-body) @@ -34,14 +34,14 @@ Use `define-private` when you need to: - Break down large functions into smaller, more manageable pieces. - Improve the readability and maintainability of your contract. -## Best Practices +## Best practices - Use descriptive names for private functions to clearly indicate their purpose. - Keep private functions focused on a single task or operation. - Use private functions to avoid code duplication within your contract. - Remember that private functions can return any type, not just response types. -## Practical Example: Helper Function for Validation +## Practical example: Helper function for validation Let's implement a private function for input validation: @@ -66,13 +66,13 @@ This example demonstrates: 2. Calling the private function from within a public function. 3. Improving code readability by separating validation logic. -## Common Pitfalls +## Common pitfalls 1. Attempting to call private functions from outside the contract, which is not allowed. 2. Overusing private functions, leading to overly complex contract structure. 3. Forgetting that private functions can modify contract state, which may lead to unexpected behavior if not carefully managed. -## Related Functions +## Related functions - `define-public`: Used to define public functions that can be called from outside the contract. - `define-read-only`: Used to define public read-only functions that don't modify contract state. diff --git a/content/docs/stacks/clarity/functions/define-public.mdx b/content/docs/stacks/clarity/functions/define-public.mdx index ba2580df..0df6c9ca 100644 --- a/content/docs/stacks/clarity/functions/define-public.mdx +++ b/content/docs/stacks/clarity/functions/define-public.mdx @@ -3,7 +3,7 @@ title: define-public description: Defining public functions in Clarity smart contracts. --- -## Function Signature +## Function signature ```clarity (define-public (function-name (arg-name-0 arg-type-0) ...) function-body) @@ -34,7 +34,7 @@ Use `define-public` when you need to: - Define functions that other contracts can call via `contract-call?`. - Create functions that modify contract state and need to be invoked through transactions. -## Best Practices +## Best practices - Always return a response type (`(response T E)`) from public functions. - Use descriptive names for public functions to clearly indicate their purpose. @@ -87,14 +87,14 @@ This example demonstrates: 2. Setting a value only if it meets a condition. 3. Returning a response type to indicate success or failure. -## Common Pitfalls +## Common pitfalls 1. Forgetting to return a response type, which will cause a contract to be invalid. 2. Not implementing proper access controls, potentially allowing unauthorized actions. 3. Overlooking potential error conditions or edge cases. 4. Creating functions that are too complex or gas-intensive for practical use. -## Related Functions +## Related functions - `define-private`: Used to define private functions that can only be called within the contract. - `define-read-only`: Used to define public read-only functions that don't modify contract state. diff --git a/content/docs/stacks/clarity/functions/define-read-only.mdx b/content/docs/stacks/clarity/functions/define-read-only.mdx index b5844bf8..9648c5f7 100644 --- a/content/docs/stacks/clarity/functions/define-read-only.mdx +++ b/content/docs/stacks/clarity/functions/define-read-only.mdx @@ -3,7 +3,7 @@ title: define-read-only description: Defining public read-only functions in Clarity smart contracts. --- -## Function Signature +## Function signature ```clarity (define-read-only (function-name (arg-name-0 arg-type-0) ...) function-body) @@ -34,14 +34,14 @@ Use `define-read-only` when you need to: - Provide public interfaces for querying contract data without modifying state. - Create helper functions that other contracts can call without incurring state change costs. -## Best Practices +## Best practices - Use descriptive names for read-only functions to clearly indicate their purpose. - Ensure that read-only functions do not attempt to modify contract state. - Utilize read-only functions for complex calculations that don't require state changes. - Consider using read-only functions in combination with public functions to separate read and write operations. -## Practical Example: Token Balance Checker +## Practical example: Token balance checker Let's implement a read-only function for checking token balances: @@ -57,13 +57,13 @@ This example demonstrates: 1. Using `define-read-only` to create functions for querying token balances. 2. Implementing a getter function for individual account balances. -## Common Pitfalls +## Common pitfalls 1. Attempting to modify contract state within a read-only function, which will cause an error. 2. Overusing read-only functions for complex calculations that might be better suited for off-chain computation. 3. Forgetting that read-only functions can still consume gas when called, even though they don't modify state. -## Related Functions +## Related functions - `define-public`: Used to define public functions that can modify contract state. - `define-private`: Used to define private functions that can only be called within the contract. diff --git a/content/docs/stacks/clarity/functions/define-trait.mdx b/content/docs/stacks/clarity/functions/define-trait.mdx index 749037e4..17702a3b 100644 --- a/content/docs/stacks/clarity/functions/define-trait.mdx +++ b/content/docs/stacks/clarity/functions/define-trait.mdx @@ -3,7 +3,7 @@ title: define-trait description: Defining traits for interface-like behavior in Clarity smart contracts. --- -## Function Signature +## Function signature ```clarity (define-trait trait-name ((func1-name (arg1-type arg2-type ...) (return-type)) ...)) @@ -34,14 +34,14 @@ Use `define-trait` when you need to: - Establish standards for token contracts or other common smart contract patterns. - Enable more flexible and modular smart contract architectures. -## Best Practices +## Best practices - Use clear and descriptive names for traits and their functions. - Keep traits focused on a single responsibility or concept. - Consider creating traits for common patterns like token standards. - Use traits in combination with `use-trait` and `contract-call?` for dynamic contract interactions. -## Practical Example: Token Trait +## Practical example: Token trait Let's define a simple trait for a token contract: @@ -57,16 +57,16 @@ Let's define a simple trait for a token contract: This example demonstrates: 1. Defining a trait with multiple functions. -2. Specifying function signatures with argument types and return types. +2. Specifying Function signatures with argument types and return types. 3. Using response types to handle success and failure cases. -## Common Pitfalls +## Common pitfalls 1. Defining overly complex traits that are difficult for other contracts to implement. 2. Forgetting that traits are not implementations, just interface definitions. 3. Not considering backwards compatibility when updating traits in newer contract versions. -## Related Functions +## Related functions - `use-trait`: Used to import trait definitions from other contracts. - `impl-trait`: Used to declare that a contract implements a specific trait. diff --git a/content/docs/stacks/clarity/functions/divide.mdx b/content/docs/stacks/clarity/functions/divide.mdx index 802f5cbb..cb4dd704 100644 --- a/content/docs/stacks/clarity/functions/divide.mdx +++ b/content/docs/stacks/clarity/functions/divide.mdx @@ -5,7 +5,7 @@ description: Using the division function for arithmetic operations in Clarity sm The division function (`/`) in Clarity performs integer division on a variable number of integer inputs. It's a fundamental arithmetic operation used in many smart contract calculations. -## Function Signature +## Function signature ```clarity (/ i1 i2...) @@ -32,14 +32,14 @@ Use the division function when you need to: - Distribute resources evenly among participants. - Implement mathematical formulas that involve division. -## Best Practices +## Best practices - Always consider the possibility of division by zero, which throws a runtime error. - Be aware that Clarity uses integer division, so results are always rounded down. - Use appropriate types (int or uint) based on your needs and expected value ranges. - Consider using multiplication by fractions instead of division for more precise calculations. -## Practical Example: Token Distribution Contract +## Practical example: Token distribution contract Let's implement a simple token distribution contract that uses division to allocate tokens evenly: @@ -92,13 +92,13 @@ This example demonstrates: 2. Handling potential division by zero by checking the number of participants. 3. Using integer division to evenly distribute tokens among participants. -## Common Pitfalls +## Common pitfalls 1. Forgetting to handle division by zero, which causes a runtime error. 2. Not accounting for integer division rounding down, which can lead to unexpected results. 3. Dividing before multiplying in complex calculations, potentially losing precision. -## Related Functions +## Related functions - `*`: Used for multiplication operations. - `+`: Used for addition operations. diff --git a/content/docs/stacks/clarity/functions/element-at.mdx b/content/docs/stacks/clarity/functions/element-at.mdx index f5980910..36c66b64 100644 --- a/content/docs/stacks/clarity/functions/element-at.mdx +++ b/content/docs/stacks/clarity/functions/element-at.mdx @@ -3,7 +3,7 @@ title: element-at? description: Retrieving an element from a list at a specific index in Clarity smart contracts. --- -## Function Signature +## Function signature ```clarity (element-at? list-expr uint) @@ -32,14 +32,14 @@ Use `element-at?` when you need to: - Safely handle potential out-of-bounds access in list operations. - Work with lists in a way that may involve accessing elements at varying positions. -## Best Practices +## Best practices - Always check the returned optional value to handle cases where the index is out of bounds. - Use in combination with `len` to ensure you're not attempting to access beyond the list's length. - Consider using `map` or `fold` for operations that need to process all elements instead of accessing by index. - Be mindful of the zero-based indexing when using `element-at?`. -## Practical Example: Retrieving a Specific Item +## Practical example: Retrieve a specific item Let's implement a function that retrieves an item from a todo list: @@ -78,13 +78,13 @@ This example demonstrates: 2. Handling the optional return value with `match` to provide meaningful responses. 3. Safely accessing list elements without risking out-of-bounds errors. -## Common Pitfalls +## Common pitfalls 1. Forgetting that list indices are zero-based in Clarity. 2. Not handling the case where `element-at?` returns `none` for out-of-bounds access. 3. Using `element-at?` in a loop to process all elements, which is less efficient than using `map` or `fold`. -## Related Functions +## Related functions - `list`: Used to create lists that can be accessed with `element-at?`. - `len`: Often used in conjunction with `element-at?` to check list bounds. diff --git a/content/docs/stacks/clarity/functions/err.mdx b/content/docs/stacks/clarity/functions/err.mdx index 7ac2220f..d31e31e5 100644 --- a/content/docs/stacks/clarity/functions/err.mdx +++ b/content/docs/stacks/clarity/functions/err.mdx @@ -3,7 +3,7 @@ title: err description: Constructing error responses in Clarity smart contracts. --- -## Function Signature +## Function signature ```clarity (err value) @@ -30,14 +30,14 @@ Use `err` when you need to: - Provide specific error information or codes to the caller. - Ensure that any state changes are reverted due to a failure condition. -## Best Practices +## Best practices - Use descriptive error values that help diagnose the issue. - Consider using standardized error codes across your contract. - Pair `err` with `ok` to create comprehensive response handling. - Remember that returning an `err` will cause all state changes in the current function to be rolled back. -## Practical Example: Token Transfer with Error Handling +## Practical example: Token transfer with error handling Let's implement a simple token transfer function with error handling: @@ -69,13 +69,13 @@ This example demonstrates: 2. Pairing `err` with `ok` to handle both success and failure cases. 3. Using a simple error code (u1) to indicate the type of error. -## Common Pitfalls +## Common pitfalls 1. Forgetting that returning an `err` will revert all state changes in the current function. 2. Using non-descriptive error values that make debugging difficult. 3. Inconsistent error handling across different functions in the contract. -## Related Functions +## Related functions - `ok`: Used to construct successful responses in public functions. - `asserts!`: Often used with `err` for condition checking and error reporting. diff --git a/content/docs/stacks/clarity/functions/filter.mdx b/content/docs/stacks/clarity/functions/filter.mdx index 070681c1..50d254e2 100644 --- a/content/docs/stacks/clarity/functions/filter.mdx +++ b/content/docs/stacks/clarity/functions/filter.mdx @@ -3,7 +3,7 @@ title: filter description: Filtering elements from a list based on a predicate function in Clarity smart contracts. --- -## Function Signature +## Function signature ```clarity (filter ) @@ -32,14 +32,14 @@ Use `filter` when you need to: - Implement data validation or selection logic on lists. - Prepare data for further processing by removing irrelevant elements. -## Best Practices +## Best practices - Ensure the predicate function is efficient, especially for large lists. - Use `filter` in combination with other list functions like `map` or `fold` for complex list operations. - Be mindful of gas costs when filtering large lists. - Consider using `filter` with `define-private` functions for reusable filtering logic. -## Practical Example: Filtering Even Numbers +## Practical example: Filter even numbers Let's implement a function that filters even numbers from a list: @@ -61,13 +61,13 @@ This example demonstrates: 2. Using `filter` with the `is-even` function to create a new list of even numbers. 3. Applying the filter operation to a list of integers. -## Common Pitfalls +## Common pitfalls 1. Forgetting that `filter` creates a new list and does not modify the original. 2. Using a computationally expensive predicate function, which could lead to high gas costs. 3. Not considering the potential for an empty result list if no elements match the predicate. -## Related Functions +## Related functions - `map`: Applies a function to each element in a list, transforming the elements. - `fold`: Reduces a list to a single value by applying a function to each element. diff --git a/content/docs/stacks/clarity/functions/fold.mdx b/content/docs/stacks/clarity/functions/fold.mdx index 28eb679e..9982324e 100644 --- a/content/docs/stacks/clarity/functions/fold.mdx +++ b/content/docs/stacks/clarity/functions/fold.mdx @@ -3,7 +3,7 @@ title: fold description: Reducing a sequence to a single value in Clarity smart contracts. --- -## Function Signature +## Function signature ```clarity (fold ) @@ -33,14 +33,14 @@ Use `fold` when you need to: - Apply a function to each element of a sequence while maintaining state. - Implement algorithms that would typically require recursion. -## Best Practices +## Best practices - Ensure the function passed to `fold` is commutative if the order of operations doesn't matter. - Use meaningful initial values that make sense for your aggregation. - Consider using `fold` instead of explicit loops for cleaner, more functional code. - Be mindful of the performance implications when folding over large sequences. -## Practical Example: Summing a List of Numbers +## Practical example: Sum a list of numbers Let's implement a function that sums all numbers in a list: @@ -58,13 +58,13 @@ This example demonstrates: 2. Starting with an initial value of `u0`. 3. Applying the operation to each element in the list. -## Common Pitfalls +## Common pitfalls 1. Using an initial value of the wrong type or that doesn't make sense for the operation. 2. Forgetting that `fold` processes elements from left to right, which matters for non-commutative operations. 3. Overusing `fold` for operations that might be more clearly expressed with other functions like `map` or `filter`. -## Related Functions +## Related functions - `map`: Applies a function to each element in a sequence, returning a new sequence. - `filter`: Selects elements from a sequence based on a predicate function. diff --git a/content/docs/stacks/clarity/functions/from-consensus-buff.mdx b/content/docs/stacks/clarity/functions/from-consensus-buff.mdx index cf6809ba..8bedf07d 100644 --- a/content/docs/stacks/clarity/functions/from-consensus-buff.mdx +++ b/content/docs/stacks/clarity/functions/from-consensus-buff.mdx @@ -3,7 +3,7 @@ title: from-consensus-buff? description: Deserializing a buffer into a Clarity value in Clarity smart contracts. --- -## Function Signature +## Function signature ```clarity (from-consensus-buff? type-signature buffer) @@ -32,14 +32,14 @@ Use `from-consensus-buff?` when you need to: - Implement cross-contract communication protocols involving serialized data. - Deserialize stored data that was previously serialized for efficiency. -## Best Practices +## Best practices - Always specify the correct type signature to ensure proper deserialization. - Handle the `none` case when the deserialization fails. - Use in conjunction with `to-consensus-buff?` for serialization-deserialization workflows. - Be aware of the gas costs associated with deserializing large or complex data structures. -## Practical Example: Deserializing a Tuple +## Practical example: Deserialize a tuple Let's implement a function that deserializes a buffer into a tuple: @@ -61,14 +61,14 @@ This example demonstrates: 2. Specifying the expected type structure for the deserialization. 3. Handling both successful and failed deserialization attempts. -## Common Pitfalls +## Common pitfalls 1. Specifying an incorrect type signature, leading to deserialization failures. 2. Not handling the `none` case when deserialization fails. 3. Attempting to deserialize data that wasn't properly serialized using the SIP-005 standard. 4. Overlooking potential out-of-memory errors when deserializing very large structures. -## Related Functions +## Related functions - `to-consensus-buff?`: Used to serialize Clarity values into buffers. - `unwrap-panic`: Often used to forcibly unwrap the optional result (use with caution). diff --git a/content/docs/stacks/clarity/functions/ft-burn.mdx b/content/docs/stacks/clarity/functions/ft-burn.mdx index 1f943f80..638f21c2 100644 --- a/content/docs/stacks/clarity/functions/ft-burn.mdx +++ b/content/docs/stacks/clarity/functions/ft-burn.mdx @@ -3,7 +3,7 @@ title: ft-burn? description: Burning fungible tokens in Clarity smart contracts. --- -## Function Signature +## Function signature ```clarity (ft-burn? token-name amount sender) @@ -33,14 +33,14 @@ Use `ft-burn?` when you need to: - Allow users to voluntarily destroy their tokens. - Execute deflationary mechanisms in your token economy. -## Best Practices +## Best practices - Ensure that the `sender` has sufficient balance before attempting to burn. - Use `ft-burn?` in conjunction with proper access controls. - Consider emitting events or logging burns for transparency. - Be cautious when burning tokens from a different principal than `tx-sender`. -## Practical Example: Token Burning Mechanism +## Practical example: Token burning mechanism Let's implement a simple token burning function: @@ -66,14 +66,14 @@ This example demonstrates: 2. Implementing an admin function to burn tokens from any account. 3. Using assertions to ensure only the admin can burn tokens from other accounts. -## Common Pitfalls +## Common pitfalls 1. Attempting to burn more tokens than the `sender` has in their balance. 2. Not checking the return value of `ft-burn?` to handle potential errors. 3. Allowing unauthorized burning of tokens from other accounts. 4. Forgetting that burned tokens are permanently destroyed and cannot be recovered. -## Related Functions +## Related functions - `ft-mint?`: Used to create new tokens, increasing the total supply. - `ft-transfer?`: Used to transfer tokens between principals. diff --git a/content/docs/stacks/clarity/functions/ft-get-balance.mdx b/content/docs/stacks/clarity/functions/ft-get-balance.mdx index b396a8ee..2d12c339 100644 --- a/content/docs/stacks/clarity/functions/ft-get-balance.mdx +++ b/content/docs/stacks/clarity/functions/ft-get-balance.mdx @@ -3,7 +3,7 @@ title: ft-get-balance description: Retrieving the balance of a fungible token for a principal in Clarity smart contracts. --- -## Function Signature +## Function signature ```clarity (ft-get-balance token-name principal) @@ -32,14 +32,14 @@ Use `ft-get-balance` when you need to: - Provide balance information to users or other contracts. - Verify sufficient funds for token transfers or burns. -## Best Practices +## Best practices - Use `ft-get-balance` before attempting transfers to ensure sufficient balance. - Consider caching balance results if queried frequently to optimize gas usage. - Be aware that balances can change between checks and actual token operations. - Use in combination with other ft-* functions for comprehensive token management. -## Practical Example: Balance Check Before Transfer +## Practical example: Balance check before transfer Let's implement a function that checks balance before transferring tokens: @@ -69,13 +69,13 @@ This example demonstrates: 2. Implementing a conditional transfer based on the balance check. 3. Combining `ft-get-balance` with other ft-* functions for token management. -## Common Pitfalls +## Common pitfalls 1. Assuming balances remain constant between checking and performing operations. 2. Not handling the case where a principal might not have any balance (returns 0). 3. Overusing `ft-get-balance` in loops, which can be inefficient for gas consumption. -## Related Functions +## Related functions - `ft-transfer?`: Used to transfer tokens between principals. - `ft-mint?`: Used to create new tokens, increasing the balance of a principal. diff --git a/content/docs/stacks/clarity/functions/ft-get-supply.mdx b/content/docs/stacks/clarity/functions/ft-get-supply.mdx index 6c134e69..23a8c583 100644 --- a/content/docs/stacks/clarity/functions/ft-get-supply.mdx +++ b/content/docs/stacks/clarity/functions/ft-get-supply.mdx @@ -3,7 +3,7 @@ title: ft-get-supply description: Retrieving the total supply of a fungible token in Clarity smart contracts. --- -## Function Signature +## Function signature ```clarity (ft-get-supply token-name) @@ -31,14 +31,14 @@ Use `ft-get-supply` when you need to: - Provide supply information to users or other contracts. - Verify the integrity of token operations by checking supply changes. -## Best Practices +## Best practices - Use `ft-get-supply` in combination with `ft-mint?` and `ft-burn?` to manage token supply. - Consider caching the supply result if queried frequently to optimize gas usage. - Be aware that the supply can change between checks due to minting or burning operations. - Use in conjunction with `ft-get-balance` for comprehensive token management. -## Practical Example: Supply-Limited Minting +## Practical example: Supply-limited minting Let's implement a function that mints tokens only if it doesn't exceed a certain supply cap: @@ -69,13 +69,13 @@ This example demonstrates: 2. Implementing a supply cap check to limit token minting. 3. Combining `ft-get-supply` with `ft-mint?` for supply management. -## Common Pitfalls +## Common pitfalls 1. Assuming the supply remains constant between checks and operations. 2. Not considering the potential for overflow when adding to the supply. 3. Overusing `ft-get-supply` in loops, which can be inefficient for gas consumption. -## Related Functions +## Related functions - `ft-mint?`: Used to create new tokens, increasing the total supply. - `ft-burn?`: Used to destroy tokens, decreasing the total supply. diff --git a/content/docs/stacks/clarity/functions/ft-mint.mdx b/content/docs/stacks/clarity/functions/ft-mint.mdx index 3b081674..2bb07b5c 100644 --- a/content/docs/stacks/clarity/functions/ft-mint.mdx +++ b/content/docs/stacks/clarity/functions/ft-mint.mdx @@ -3,7 +3,7 @@ title: ft-mint? description: Minting new fungible tokens in Clarity smart contracts. --- -## Function Signature +## Function signature ```clarity (ft-mint? token-name amount recipient) @@ -33,14 +33,14 @@ Use `ft-mint?` when you need to: - Increase the balance of a specific principal with new tokens. - Execute token minting operations based on certain conditions or events. -## Best Practices +## Best practices - Implement proper access controls to restrict who can mint new tokens. - Consider using a maximum supply cap to prevent unlimited minting. - Emit events or use a logging mechanism to track minting operations for transparency. - Be cautious of potential overflow when minting large amounts of tokens. -## Practical Example: Reward Minting +## Practical example: Reward minting Let's implement a simple reward system that mints tokens: @@ -65,14 +65,14 @@ This example demonstrates: 2. Implementing a basic access control check before minting. 3. Returning the result of the minting operation. -## Common Pitfalls +## Common pitfalls 1. Minting tokens without proper access controls, allowing unauthorized token creation. 2. Not considering the total supply limit, potentially leading to economic imbalances. 3. Forgetting to handle the error case when minting fails (e.g., due to supply cap). 4. Overlooking the gas costs associated with minting, especially for large amounts. -## Related Functions +## Related functions - `ft-burn?`: Used to destroy tokens, decreasing the total supply. - `ft-transfer?`: Used to transfer tokens between principals. diff --git a/content/docs/stacks/clarity/functions/ft-transfer.mdx b/content/docs/stacks/clarity/functions/ft-transfer.mdx index b039d9da..325fe7e2 100644 --- a/content/docs/stacks/clarity/functions/ft-transfer.mdx +++ b/content/docs/stacks/clarity/functions/ft-transfer.mdx @@ -3,7 +3,7 @@ title: ft-transfer? description: Transferring fungible tokens between principals in Clarity smart contracts. --- -## Function Signature +## Function signature ```clarity (ft-transfer? token-name amount sender recipient) @@ -34,7 +34,7 @@ Use `ft-transfer?` when you need to: - Allow users to send tokens to each other within your dApp. - Move tokens as part of more complex contract operations. -## Best Practices +## Best practices - Always check the return value to ensure the transfer was successful. - Implement proper access controls to prevent unauthorized transfers. @@ -42,7 +42,7 @@ Use `ft-transfer?` when you need to: - Be aware that any principal can call this function, so add necessary guards. - Verify sender has sufficient balance before attempting a transfer. -## Practical Example: Token Transfer Function +## Practical example: Token transfer function Let's implement a public function for transferring tokens with some basic checks: @@ -73,14 +73,14 @@ This example demonstrates: 2. Implementing basic checks for valid transfer conditions. 3. Handling the response from `ft-transfer?` and propagating it to the caller. -## Common Pitfalls +## Common pitfalls 1. Forgetting that `ft-transfer?` can be called by any principal, potentially leading to unauthorized transfers. 2. Not handling all possible error cases returned by `ft-transfer?`. 3. Attempting to transfer more tokens than the sender's balance. 4. Using `ft-transfer?` with a token name that hasn't been defined in the contract. -## Related Functions +## Related functions - `ft-mint?`: Used to create new tokens and assign them to a principal. - `ft-burn?`: Used to destroy tokens, reducing the balance of a principal. diff --git a/content/docs/stacks/clarity/functions/get-block-info.mdx b/content/docs/stacks/clarity/functions/get-block-info.mdx index 0b88d41c..99e2812d 100644 --- a/content/docs/stacks/clarity/functions/get-block-info.mdx +++ b/content/docs/stacks/clarity/functions/get-block-info.mdx @@ -3,7 +3,7 @@ title: get-block-info? description: Fetching information about Stacks blocks in Clarity smart contracts. --- -## Function Signature +## Function signature ```clarity (get-block-info? prop-name block-height) @@ -32,14 +32,14 @@ Use `get-block-info?` when you need to: - Verify block hashes or other block-specific data. - Access block rewards or miner spending data (in Stacks 2.1+). -## Best Practices +## Best practices - Always check if the returned value is `none`, as it will be for non-existent or future blocks. - Be aware of the potential for chain reorganizations when using recent block data. - Use the appropriate property name for the data you need to retrieve. - Consider caching results for frequently accessed block information to save on execution costs. -## Practical Example: Block Time Verification +## Practical example: Block time verification Let's implement a function that checks if a given block was mined after a certain time: @@ -72,14 +72,14 @@ New in Stacks 2.1: - `block-reward`: Returns the total block reward (uint). - `miner-spend-total`: Returns the total spent by miners for this block (uint). -## Common Pitfalls +## Common pitfalls 1. Assuming all properties are available for all blocks (e.g., `block-reward` is only available for mature blocks). 2. Not handling the `none` case when the block height is invalid or in the future. 3. Relying on exact block times, which can be inaccurate up to two hours. 4. Using `header-hash` when global uniqueness is required (use `id-header-hash` instead). -## Related Functions +## Related functions - `get-burn-block-info?`: Used to get information about the underlying burn chain blocks. - `block-height`: Keyword that returns the current block height. diff --git a/content/docs/stacks/clarity/functions/get-burn-block-info.mdx b/content/docs/stacks/clarity/functions/get-burn-block-info.mdx index cd92f677..810cd77a 100644 --- a/content/docs/stacks/clarity/functions/get-burn-block-info.mdx +++ b/content/docs/stacks/clarity/functions/get-burn-block-info.mdx @@ -3,7 +3,7 @@ title: get-burn-block-info? description: Fetching information about burnchain blocks in Clarity smart contracts. --- -## Function Signature +## Function signature ```clarity (get-burn-block-info? prop-name block-height) @@ -32,16 +32,16 @@ Use `get-burn-block-info?` when you need to: - Implement logic that depends on burnchain block data. - Build cross-chain applications that reference Bitcoin state. -## Best Practices +## Best practices - Always check if the returned value is `none`, as it will be for non-existent or future blocks. - Be aware of the potential for chain reorganizations when using recent block data. - Use the appropriate property name for the data you need to retrieve. - Consider caching results for frequently accessed block information to save on execution costs. -## Practical Example: Verifying a Bitcoin Block Hash +## Practical example: Verify a bitcoin block hash -Let's implement a function that verifies if a given Bitcoin block hash matches a specific height: +Let's implement a function that verifies if a given bitcoin block hash matches a specific height: ```clarity (define-read-only (verify-btc-block-hash (height uint) (expectedHash (buff 32))) @@ -67,14 +67,14 @@ This example demonstrates: - `addrs`: A list of up to two PoX addresses that received payouts. - `payout`: The amount of burnchain tokens paid to each address. -## Common Pitfalls +## Common pitfalls 1. Assuming all properties are available for all blocks. 2. Not handling the `none` case when the block height is invalid or in the future. 3. Misinterpreting the `pox-addrs` data, especially during different PoX phases. 4. Overlooking the fact that burn addresses may be included in the `pox-addrs` list. -## Related Functions +## Related functions - `get-block-info?`: Used to get information about Stacks blocks. - `burn-block-height`: Keyword that returns the current burn chain block height. diff --git a/content/docs/stacks/clarity/functions/get.mdx b/content/docs/stacks/clarity/functions/get.mdx index a7e82fbf..45cd543e 100644 --- a/content/docs/stacks/clarity/functions/get.mdx +++ b/content/docs/stacks/clarity/functions/get.mdx @@ -3,7 +3,7 @@ title: get description: Retrieving a value from a tuple in Clarity smart contracts. --- -## Function Signature +## Function signature ```clarity (get key-name tuple) @@ -32,14 +32,14 @@ Use `get` when you need to: - Work with complex data types in your contract logic. - Implement data processing that involves tuple manipulation. -## Best Practices +## Best practices - Ensure the key exists in the tuple to avoid runtime errors. - Use meaningful key names for better code readability. - Consider using `get` in combination with `optional` for safer data access. - Be aware of the performance implications when working with large tuples. -## Practical Example: User Profile Management +## Practical example: User profile management Let's implement a simple user profile system using tuples and the `get` function: @@ -75,13 +75,13 @@ This example demonstrates: 2. Implementing getter functions that use `get` to access tuple data. 3. Handling cases where the profile might not exist. -## Common Pitfalls +## Common pitfalls 1. Attempting to `get` a key that doesn't exist in the tuple, causing a runtime error. 2. Forgetting that `get` is case-sensitive for key names. 3. Not considering the performance impact of frequently accessing large tuples. -## Related Functions +## Related functions - `merge`: Used to combine tuples, potentially creating new fields to `get`. - `tuple`: Used to create tuples that can be accessed with `get`. diff --git a/content/docs/stacks/clarity/functions/greater-than-or-equal.mdx b/content/docs/stacks/clarity/functions/greater-than-or-equal.mdx index d797c9dd..ce6cfeba 100644 --- a/content/docs/stacks/clarity/functions/greater-than-or-equal.mdx +++ b/content/docs/stacks/clarity/functions/greater-than-or-equal.mdx @@ -5,7 +5,7 @@ description: Using the greater than or equal function for comparisons in Clarity The greater than or equal function (`>=`) in Clarity compares two values and returns true if the first value is greater than or equal to the second. It's a fundamental comparison operation used in many smart contract conditions and logic flows. -## Function Signature +## Function signature ```clarity (>= v1 v2) @@ -33,7 +33,7 @@ Use the greater than or equal function when you need to: - Create conditional logic based on numerical comparisons, including equality. - Sort or order data based on numerical or lexicographical order, including equal values. -## Best Practices +## Best practices - Ensure that both inputs are of the same type to avoid runtime errors. - Be aware of the differences in comparison between signed (int) and unsigned (uint) integers. @@ -41,7 +41,7 @@ Use the greater than or equal function when you need to: - Consider edge cases, especially when dealing with the limits of integer ranges. - Use `>=` instead of `>` when you want to include equality in your comparison. -## Practical Example: Token Unlock Schedule +## Practical example: Token unlock schedule Let's implement a simple token unlock schedule that uses the greater than or equal function to manage token releases: @@ -98,13 +98,13 @@ This example demonstrates: 2. Combining the greater than or equal check with other contract logic for a token unlock system. 3. Implementing a minimum threshold (the unlock interval) that includes the exact unlock time. -## Common Pitfalls +## Common pitfalls 1. Comparing values of different types, which will result in a runtime error. 2. Confusing `>=` with `>` when setting thresholds, potentially excluding valid values. 3. Overlooking the inclusive nature of `>=` in boundary conditions. -## Related Functions +## Related functions - `>`: Used for strict greater than comparisons. - `<`: Used for less than comparisons. diff --git a/content/docs/stacks/clarity/functions/greater-than.mdx b/content/docs/stacks/clarity/functions/greater-than.mdx index 689c54b2..0455b004 100644 --- a/content/docs/stacks/clarity/functions/greater-than.mdx +++ b/content/docs/stacks/clarity/functions/greater-than.mdx @@ -5,7 +5,7 @@ description: Using the greater than function for comparisons in Clarity smart co The greater than function (`>`) in Clarity compares two values and returns true if the first value is greater than the second. It's a fundamental comparison operation used in many smart contract conditions and logic flows. -## Function Signature +## Function signature ```clarity (> v1 v2) @@ -32,14 +32,14 @@ Use the greater than function when you need to: - Create conditional logic based on numerical comparisons. - Sort or order data based on numerical or lexicographical order. -## Best Practices +## Best practices - Ensure that both inputs are of the same type to avoid runtime errors. - Be aware of the differences in comparison between signed (int) and unsigned (uint) integers. - When comparing strings or buffers, understand that the comparison is lexicographical. - Consider edge cases, especially when dealing with the limits of integer ranges. -## Practical Example: Token Sale with Minimum Purchase +## Practical example: Token sale with minimum purchase Let's implement a simple token sale contract that uses the greater than function to enforce a minimum purchase amount: @@ -79,13 +79,13 @@ This example demonstrates: 2. Combining the greater than check with other contract logic for a token sale. 3. Implementing a minimum purchase amount to prevent small, potentially spam transactions. -## Common Pitfalls +## Common pitfalls 1. Comparing values of different types, which will result in a runtime error. 2. Not considering the inclusive nature of `>=` vs the exclusive nature of `>` when setting thresholds. 3. Overlooking potential integer overflow when working with very large numbers. -## Related Functions +## Related functions - `<`: Used for less than comparisons. - `>=`: Used for greater than or equal to comparisons. diff --git a/content/docs/stacks/clarity/functions/hash160.mdx b/content/docs/stacks/clarity/functions/hash160.mdx index ef3c7901..b71544a8 100644 --- a/content/docs/stacks/clarity/functions/hash160.mdx +++ b/content/docs/stacks/clarity/functions/hash160.mdx @@ -3,7 +3,7 @@ title: hash160 description: Computing the RIPEMD160(SHA256(x)) hash in Clarity smart contracts. --- -## Function Signature +## Function signature ```clarity (hash160 value) @@ -30,14 +30,14 @@ Use `hash160` when you need to: - Create short, unique identifiers for data structures. - Perform cryptographic operations that require RIPEMD160(SHA256(x)). -## Best Practices +## Best practices - Use `hash160` when you need a shorter hash than SHA256 but still want strong collision resistance. - Be aware that `hash160` is not reversible; it's a one-way function. - When hashing sensitive data, consider using additional security measures like salting. - Remember that for integers, the hash is computed over their little-endian representation. -## Practical Example: Simple Address Generation +## Practical example: Simple address generation Let's implement a function that generates a simple hash-based identifier: @@ -55,14 +55,14 @@ This example demonstrates: 1. Using `hash160` to create a compact identifier from input data. 2. The function takes a 32-byte buffer and returns a 20-byte hash. -## Common Pitfalls +## Common pitfalls 1. Assuming `hash160` output is the same length as `sha256` output (it's shorter at 20 bytes). 2. Using `hash160` where a longer hash might be more appropriate for security reasons. 3. Forgetting that integer inputs are hashed in their little-endian representation. 4. Not considering that `hash160` is computationally more expensive than a single `sha256`. -## Related Functions +## Related functions - `sha256`: Computes the SHA256 hash of the input. - `ripemd160`: Computes the RIPEMD160 hash of the input (not directly available in Clarity, but `hash160` combines SHA256 and RIPEMD160). diff --git a/content/docs/stacks/clarity/functions/if.mdx b/content/docs/stacks/clarity/functions/if.mdx index 16dc1122..bc6ef9b2 100644 --- a/content/docs/stacks/clarity/functions/if.mdx +++ b/content/docs/stacks/clarity/functions/if.mdx @@ -3,7 +3,7 @@ title: if description: Conditional evaluation in Clarity smart contracts. --- -## Function Signature +## Function signature ```clarity (if bool expr1 expr2) @@ -33,14 +33,14 @@ Use `if` when you need to: - Control the flow of your contract based on dynamic conditions. - Simplify complex decision-making processes. -## Best Practices +## Best practices - Ensure that both `expr1` and `expr2` return the same type. - Use clear and meaningful boolean expressions for readability. - Avoid deeply nested `if` statements for better maintainability. - Combine with other control flow functions like `match` for more complex logic. -## Practical Example: Conditional Token Transfer +## Practical example: Conditional token transfer ```clarity (define-map UserBalances { userId: principal } { balance: uint }) @@ -67,14 +67,14 @@ This example demonstrates: 2. Executing different code paths based on the result of the balance check. 3. Handling both the success and failure cases appropriately. -## Common Pitfalls +## Common pitfalls 1. Forgetting that both `expr1` and `expr2` must return the same type. 2. Using overly complex boolean expressions, making the code hard to read. 3. Not handling all possible conditions, leading to unexpected behavior. 4. Overusing `if` for logic that could be simplified with other control flow functions. -## Related Functions +## Related functions - `match`: Used for pattern matching and handling multiple conditions. - `and`: Logical AND operator for combining boolean expressions. diff --git a/content/docs/stacks/clarity/functions/impl-trait.mdx b/content/docs/stacks/clarity/functions/impl-trait.mdx index bc08198e..9ec4fe23 100644 --- a/content/docs/stacks/clarity/functions/impl-trait.mdx +++ b/content/docs/stacks/clarity/functions/impl-trait.mdx @@ -3,7 +3,7 @@ title: impl-trait description: Implementing traits in Clarity smart contracts. --- -## Function Signature +## Function signature ```clarity (impl-trait trait-name) @@ -31,14 +31,14 @@ Use `impl-trait` when you need to: - Ensure your contract adheres to specific standards or behaviors. - Enable dynamic function calls using `contract-call?`. -## Best Practices +## Best practices - Define traits at the top level of your contract for clarity and organization. - Ensure all required functions in the trait are implemented in your contract. - Use meaningful and descriptive names for traits and their functions. - Document the purpose and usage of each trait in your contract. -## Practical Example: Implementing a Token Trait +## Practical example: Implement a token trait Let's define a simple token trait and implement it in a contract: @@ -81,14 +81,14 @@ This example demonstrates: 2. Implementing the `token-trait` in a contract using `impl-trait`. 3. Providing implementations for the `transfer` and `get-balance` functions. -## Common Pitfalls +## Common pitfalls 1. Forgetting to implement all required functions in the trait, leading to deployment errors. -2. Using inconsistent function signatures between the trait and the implementation. +2. Using inconsistent Function signatures between the trait and the implementation. 3. Not documenting the purpose and usage of traits, making the contract harder to understand. 4. Overlooking the need for proper error handling in trait functions. -## Related Functions +## Related functions - `define-trait`: Used to define a new trait. - `contract-call?`: Used to call functions dynamically on contracts that implement a trait. diff --git a/content/docs/stacks/clarity/functions/index-of.mdx b/content/docs/stacks/clarity/functions/index-of.mdx index d90d1e0f..dd993134 100644 --- a/content/docs/stacks/clarity/functions/index-of.mdx +++ b/content/docs/stacks/clarity/functions/index-of.mdx @@ -3,7 +3,7 @@ title: index-of description: Finding the index of an element in a list in Clarity smart contracts. --- -## Function Signature +## Function signature ```clarity (index-of list element) @@ -32,14 +32,14 @@ Use `index-of` when you need to: - Implement logic that depends on the order or position of elements. - Simplify list search operations without writing custom loops. -## Best Practices +## Best practices - Ensure the list and element types are compatible. - Handle the `none` case when the element is not found in the list. - Use meaningful variable names for better readability. - Consider the performance implications when searching large lists. -## Practical Example: Finding an Element in a List +## Practical example: Find an element in a list Let's implement a function that finds the index of a given element in a list of integers: @@ -57,14 +57,14 @@ This example demonstrates: 1. Using `index-of` to find the position of an element in a list. 2. Handling both the case where the element is found and where it is not found. -## Common Pitfalls +## Common pitfalls 1. Assuming the element will always be found, leading to unhandled `none` cases. 2. Using `index-of` on lists with incompatible element types. 3. Overlooking the performance impact of searching very large lists. 4. Not considering that `index-of` returns a 0-based index. -## Related Functions +## Related functions - `filter`: Used to create a new list containing only elements that match a condition. - `map`: Applies a function to each element in a list, transforming the elements. diff --git a/content/docs/stacks/clarity/functions/int-to-ascii.mdx b/content/docs/stacks/clarity/functions/int-to-ascii.mdx index 54fbfc2f..f1497681 100644 --- a/content/docs/stacks/clarity/functions/int-to-ascii.mdx +++ b/content/docs/stacks/clarity/functions/int-to-ascii.mdx @@ -3,7 +3,7 @@ title: int-to-ascii description: Converting integers to ASCII string representations in Clarity smart contracts. --- -## Function Signature +## Function signature ```clarity (int-to-ascii value) @@ -30,14 +30,14 @@ Use `int-to-ascii` when you need to: - Log or store numeric data as strings. - Prepare numeric data for concatenation with other strings. -## Best Practices +## Best practices - Ensure the integer value is within the range that can be represented as a string. - Use meaningful variable names for better readability. - Combine with other string functions for more complex string manipulations. - Be aware of the maximum length of the resulting string (40 characters). -## Practical Example: Logging a User's Balance +## Practical example: Log a user's balance Let's implement a function that logs a user's balance as a string: @@ -64,14 +64,14 @@ This example demonstrates: 2. Logging the string representation of the balance using `print`. 3. Handling the case where the user has no balance set. -## Common Pitfalls +## Common pitfalls 1. Assuming the resulting string will always fit within 40 characters. 2. Forgetting to handle cases where the integer value is not set or is zero. 3. Using `int-to-ascii` in performance-critical sections without considering the overhead. 4. Not combining with other string functions for more complex manipulations. -## Related Functions +## Related functions - `print`: Used to log or display string values. - `concat`: Used to concatenate multiple strings. diff --git a/content/docs/stacks/clarity/functions/int-to-utf8.mdx b/content/docs/stacks/clarity/functions/int-to-utf8.mdx index 4071e82c..a5ff2519 100644 --- a/content/docs/stacks/clarity/functions/int-to-utf8.mdx +++ b/content/docs/stacks/clarity/functions/int-to-utf8.mdx @@ -3,7 +3,7 @@ title: int-to-utf8 description: Converting integers to UTF-8 string representations in Clarity smart contracts. --- -## Function Signature +## Function signature ```clarity (int-to-utf8 value) @@ -33,14 +33,14 @@ Use `int-to-utf8` when you need to: - Log or store numeric data as UTF-8 strings. - Prepare numeric data for concatenation with other UTF-8 strings. -## Best Practices +## Best practices - Ensure the integer value is within the range that can be represented as a string. - Use meaningful variable names for better readability. - Combine with other string functions for more complex string manipulations. - Be aware of the maximum length of the resulting string (40 characters). -## Practical Example: Logging a User's Balance +## Practical example: Log a user's balance Let's implement a function that logs a user's balance as a UTF-8 string: @@ -70,14 +70,14 @@ This example demonstrates: 2. Logging the string representation of the balance using `print`. 3. Handling the case where the user has no balance set. -## Common Pitfalls +## Common pitfalls 1. Assuming the resulting string will always fit within 40 characters. 2. Forgetting to handle cases where the integer value is not set or is zero. 3. Using `int-to-utf8` in performance-critical sections without considering the overhead. 4. Not combining with other string functions for more complex manipulations. -## Related Functions +## Related functions - `print`: Used to log or display string values. - `concat`: Used to concatenate multiple strings. diff --git a/content/docs/stacks/clarity/functions/is-eq.mdx b/content/docs/stacks/clarity/functions/is-eq.mdx index 8b39a6d0..a56eac09 100644 --- a/content/docs/stacks/clarity/functions/is-eq.mdx +++ b/content/docs/stacks/clarity/functions/is-eq.mdx @@ -3,7 +3,7 @@ title: is-eq description: Comparing values for equality in Clarity smart contracts. --- -## Function Signature +## Function signature ```clarity (is-eq v1 v2 ...) @@ -33,14 +33,14 @@ Use `is-eq` when you need to: - Verify that input values match expected constants or variables. - Simplify equality checks in your contract. -## Best Practices +## Best practices - Ensure all values being compared are of the same type to avoid type errors. - Use `is-eq` for simple equality checks and combine with other logical functions for complex conditions. - Be aware that `is-eq` does not short-circuit; all values are evaluated. - Use meaningful variable names for better readability. -## Practical Example: Checking User Role +## Practical example: Check user role Let's implement a function that checks if a user has a specific role: @@ -70,14 +70,14 @@ This example demonstrates: 2. Handling the case where the user role is not set by providing a default value. 3. Implementing a read-only function to check if a user is an admin. -## Common Pitfalls +## Common pitfalls 1. Comparing values of different types, leading to type errors. 2. Assuming `is-eq` short-circuits like `and` or `or` (it does not). 3. Using `is-eq` for complex conditions where other logical functions might be more appropriate. 4. Not handling cases where values might be `none` or unset. -## Related Functions +## Related functions - `is-some`: Checks if an optional value is `some`. - `is-none`: Checks if an optional value is `none`. diff --git a/content/docs/stacks/clarity/functions/is-err.mdx b/content/docs/stacks/clarity/functions/is-err.mdx index daf273db..7f7f7017 100644 --- a/content/docs/stacks/clarity/functions/is-err.mdx +++ b/content/docs/stacks/clarity/functions/is-err.mdx @@ -3,7 +3,7 @@ title: is-err description: Checking if a response is an error in Clarity smart contracts. --- -## Function Signature +## Function signature ```clarity (is-err value) @@ -30,14 +30,14 @@ Use `is-err` when you need to: - Validate the results of function calls that return response types. - Handle errors gracefully in your contract logic. -## Best Practices +## Best practices - Use `is-err` in combination with `match` or `if` for comprehensive error handling. - Ensure that the response value being checked is of the correct type. - Use meaningful variable names for better readability. - Combine with other response handling functions like `is-ok` for complete validation. -## Practical Example: Validating a Token Transfer +## Practical example: Validate a token transfer Let's implement a function that validates a token transfer and checks for errors: @@ -76,14 +76,14 @@ This example demonstrates: 2. Implementing conditional logic based on the success or failure of the transfer. 3. Handling both the success and error cases appropriately. -## Common Pitfalls +## Common pitfalls 1. Assuming the response value is always of the correct type, leading to type errors. 2. Not handling all possible error cases, resulting in incomplete error handling. 3. Overlooking the need for comprehensive validation and error checking. 4. Using `is-err` without meaningful error codes or messages, making debugging harder. -## Related Functions +## Related functions - `is-ok`: Checks if a response value is `ok`. - `err`: Constructs an error response. diff --git a/content/docs/stacks/clarity/functions/is-none.mdx b/content/docs/stacks/clarity/functions/is-none.mdx index b98105cc..7565cb19 100644 --- a/content/docs/stacks/clarity/functions/is-none.mdx +++ b/content/docs/stacks/clarity/functions/is-none.mdx @@ -3,7 +3,7 @@ title: is-none description: Checking if an optional value is none in Clarity smart contracts. --- -## Function Signature +## Function signature ```clarity (is-none value) @@ -30,14 +30,14 @@ Use `is-none` when you need to: - Validate the results of function calls that return optional types. - Handle cases where values might be missing or not set. -## Best Practices +## Best practices - Use `is-none` in combination with `match` or `if` for comprehensive value handling. - Ensure that the value being checked is of the correct optional type. - Use meaningful variable names for better readability. - Combine with other optional handling functions like `is-some` for complete validation. -## Practical Example: Checking for Missing User Data +## Practical example: Check for missing user data Let's implement a function that checks if a user's profile data is missing: @@ -59,14 +59,14 @@ This example demonstrates: 2. Implementing a read-only function to determine the presence of user data. 3. Handling both the case where the profile data is present and where it is missing. -## Common Pitfalls +## Common pitfalls 1. Assuming the value will always be `some`, leading to unhandled `none` cases. 2. Using `is-none` on non-optional types, causing type errors. 3. Not handling all possible conditions, resulting in incomplete value checks. 4. Overlooking the need for comprehensive validation and error checking. -## Related Functions +## Related functions - `is-some`: Checks if an optional value is `some`. - `match`: Used for pattern matching and handling multiple conditions. diff --git a/content/docs/stacks/clarity/functions/is-ok.mdx b/content/docs/stacks/clarity/functions/is-ok.mdx index 4852fe90..e8e5bbc7 100644 --- a/content/docs/stacks/clarity/functions/is-ok.mdx +++ b/content/docs/stacks/clarity/functions/is-ok.mdx @@ -3,7 +3,7 @@ title: is-ok description: Checking if a response is ok in Clarity smart contracts. --- -## Function Signature +## Function signature ```clarity (is-ok value) @@ -30,14 +30,14 @@ Use `is-ok` when you need to: - Validate the results of function calls that return response types. - Handle success cases gracefully in your contract logic. -## Best Practices +## Best practices - Use `is-ok` in combination with `match` or `if` for comprehensive response handling. - Ensure that the response value being checked is of the correct type. - Use meaningful variable names for better readability. - Combine with other response handling functions like `is-err` for complete validation. -## Practical Example: Validating a Token Transfer +## Practical example: Validate a token transfer Let's implement a function that validates a token transfer and checks for success: @@ -76,14 +76,14 @@ This example demonstrates: 2. Implementing conditional logic based on the success of the transfer. 3. Handling both the success and error cases appropriately. -## Common Pitfalls +## Common pitfalls 1. Assuming the response value is always of the correct type, leading to type errors. 2. Not handling all possible success and error cases, resulting in incomplete response handling. 3. Overlooking the need for comprehensive validation and error checking. 4. Using `is-ok` without meaningful success codes or messages, making debugging harder. -## Related Functions +## Related functions - `is-err`: Checks if a response value is `err`. - `err`: Constructs an error response. diff --git a/content/docs/stacks/clarity/functions/is-some.mdx b/content/docs/stacks/clarity/functions/is-some.mdx index add4ea83..26cea49a 100644 --- a/content/docs/stacks/clarity/functions/is-some.mdx +++ b/content/docs/stacks/clarity/functions/is-some.mdx @@ -3,7 +3,7 @@ title: is-some description: Checking if an optional value is some in Clarity smart contracts. --- -## Function Signature +## Function signature ```clarity (is-some value) @@ -30,14 +30,14 @@ Use `is-some` when you need to: - Validate the results of function calls that return optional types. - Handle cases where values might be present or absent. -## Best Practices +## Best practices - Use `is-some` in combination with `match` or `if` for comprehensive value handling. - Ensure that the value being checked is of the correct optional type. - Use meaningful variable names for better readability. - Combine with other optional handling functions like `is-none` for complete validation. -## Practical Example: Checking for Existing User Data +## Practical example: Check for existing user data Let's implement a function that checks if a user's profile data exists: @@ -59,14 +59,14 @@ This example demonstrates: 2. Implementing a read-only function to determine the presence of user data. 3. Handling both the case where the profile data is present and where it is absent. -## Common Pitfalls +## Common pitfalls 1. Assuming the value will always be `some`, leading to unhandled `none` cases. 2. Using `is-some` on non-optional types, causing type errors. 3. Not handling all possible conditions, resulting in incomplete value checks. 4. Overlooking the need for comprehensive validation and error checking. -## Related Functions +## Related functions - `is-none`: Checks if an optional value is `none`. - `match`: Used for pattern matching and handling multiple conditions. diff --git a/content/docs/stacks/clarity/functions/is-standard.mdx b/content/docs/stacks/clarity/functions/is-standard.mdx index 3d5cb156..f25ae65f 100644 --- a/content/docs/stacks/clarity/functions/is-standard.mdx +++ b/content/docs/stacks/clarity/functions/is-standard.mdx @@ -3,7 +3,7 @@ title: is-standard description: Checking if a value is a standard principal in Clarity smart contracts. --- -## Function Signature +## Function signature ```clarity (is-standard value) @@ -30,14 +30,14 @@ Use `is-standard` when you need to: - Validate the type of principal before performing certain operations. - Handle cases where only standard principals are allowed. -## Best Practices +## Best practices - Use `is-standard` in combination with `if` or `match` for comprehensive principal type handling. - Ensure that the value being checked is of the correct principal type. - Use meaningful variable names for better readability. - Note that you can pass in a valid contract principal as well, not just a standard principal (e.g., `'SP12` or `'SP12.contract`). -## Practical Example: Restricting Access to Standard Principals +## Practical example: Restrict access to standard principals Let's implement a function that restricts access to standard principals: @@ -74,14 +74,14 @@ This example demonstrates: 2. Implementing conditional logic based on the type of principal. 3. Handling both the case where the principal is standard and where it is not. -## Common Pitfalls +## Common pitfalls 1. Assuming the principal will always be standard, leading to unhandled cases. 2. Using `is-standard` on non-principal types, causing type errors. 3. Not handling all possible conditions, resulting in incomplete principal type checks. 4. Overlooking the need for comprehensive validation and error checking. -## Related Functions +## Related functions - `tx-sender`: Returns the principal that initiated the transaction. - `contract-caller`: Returns the caller of the current contract context. diff --git a/content/docs/stacks/clarity/functions/keccak256.mdx b/content/docs/stacks/clarity/functions/keccak256.mdx index f4c51c56..3a313717 100644 --- a/content/docs/stacks/clarity/functions/keccak256.mdx +++ b/content/docs/stacks/clarity/functions/keccak256.mdx @@ -3,7 +3,7 @@ title: keccak256 description: Computing the Keccak-256 hash of a buffer in Clarity smart contracts. --- -## Function Signature +## Function signature ```clarity (keccak256 value) @@ -30,14 +30,14 @@ Use `keccak256` when you need to: - Generate unique identifiers for data. - Implement cryptographic operations in your contract. -## Best Practices +## Best practices - Ensure the input buffer is of the correct length and format. - Use meaningful variable names for better readability. - Combine with other cryptographic functions for more complex operations. - Be aware of the security implications of using cryptographic hashes. -## Practical Example: Hashing a User's Data +## Practical example: Hash a user's data Let's implement a function that computes the Keccak-256 hash of a user's data: @@ -64,14 +64,14 @@ This example demonstrates: 2. Implementing a public function to return the hash. 3. Handling the case where the user's data is not set by providing a default value. -## Common Pitfalls +## Common pitfalls 1. Using `keccak256` on non-buffer types, causing type errors. 2. Not handling cases where the input buffer is empty or invalid. 3. Overlooking the need for proper error handling and validation. 4. Assuming the hash function is collision-resistant without understanding its limitations. -## Related Functions +## Related functions - `sha256`: Computes the SHA-256 hash of a buffer. - `hash160`: Computes the RIPEMD-160 hash of the SHA-256 hash of a buffer. diff --git a/content/docs/stacks/clarity/functions/len.mdx b/content/docs/stacks/clarity/functions/len.mdx index e4514c2a..e60eb54e 100644 --- a/content/docs/stacks/clarity/functions/len.mdx +++ b/content/docs/stacks/clarity/functions/len.mdx @@ -3,7 +3,7 @@ title: len description: Getting the length of a sequence in Clarity smart contracts. --- -## Function Signature +## Function signature ```clarity (len sequence) @@ -30,14 +30,14 @@ Use `len` when you need to: - Validate the length of input data. - Handle cases where the size of a sequence is important. -## Best Practices +## Best practices - Ensure the sequence type is compatible with the `len` function. - Use meaningful variable names for better readability. - Combine with other functions for comprehensive sequence handling. - Be aware of the maximum length of sequences in Clarity. -## Practical Example: Validating a List Length +## Practical example: Validate a list length Let's implement a function that validates the length of a list of integers: @@ -64,14 +64,14 @@ This example demonstrates: 2. Implementing conditional logic based on the length of the list. 3. Handling both the case where the list length is valid and where it is not. -## Common Pitfalls +## Common pitfalls 1. Using `len` on incompatible types, causing type errors. 2. Assuming the length will always be within a certain range, leading to unhandled cases. 3. Not handling all possible conditions, resulting in incomplete length checks. 4. Overlooking the need for comprehensive validation and error checking. -## Related Functions +## Related functions - `as-max-len?`: Ensures a sequence does not exceed a maximum length. - `concat`: Concatenates multiple sequences. diff --git a/content/docs/stacks/clarity/functions/less-than-or-equal.mdx b/content/docs/stacks/clarity/functions/less-than-or-equal.mdx index 1a2f73c7..9f9b1b23 100644 --- a/content/docs/stacks/clarity/functions/less-than-or-equal.mdx +++ b/content/docs/stacks/clarity/functions/less-than-or-equal.mdx @@ -5,7 +5,7 @@ description: Using the less than or equal function for comparisons in Clarity sm The less than or equal function (`<=`) in Clarity compares two values and returns true if the first value is less than or equal to the second. It's a fundamental comparison operation used in many smart contract conditions and logic flows. -## Function Signature +## Function signature ```clarity (<= v1 v2) @@ -33,7 +33,7 @@ Use the less than or equal function when you need to: - Create conditional logic based on numerical comparisons, including equality. - Sort or order data based on numerical or lexicographical order, including equal values. -## Best Practices +## Best practices - Ensure that both inputs are of the same type to avoid runtime errors. - Be aware of the differences in comparison between signed (int) and unsigned (uint) integers. @@ -41,7 +41,7 @@ Use the less than or equal function when you need to: - Consider edge cases, especially when dealing with the limits of integer ranges. - Use `<=` instead of `<` when you want to include equality in your comparison. -## Practical Example: Token Vesting Contract +## Practical example: Token vesting contract Let's implement a simple token vesting contract that uses the less than or equal function to manage vesting periods: @@ -98,13 +98,13 @@ This example demonstrates: 2. Combining the less than or equal check with other contract logic for a vesting system. 3. Implementing a maximum threshold (the vesting period) that includes the exact end time. -## Common Pitfalls +## Common pitfalls 1. Comparing values of different types, which will result in a runtime error. 2. Confusing `<=` with `<` when setting thresholds, potentially excluding valid values. 3. Overlooking the inclusive nature of `<=` in boundary conditions. -## Related Functions +## Related functions - `<`: Used for strict less than comparisons. - `>`: Used for greater than comparisons. diff --git a/content/docs/stacks/clarity/functions/less-than.mdx b/content/docs/stacks/clarity/functions/less-than.mdx index 1169985d..9af259f0 100644 --- a/content/docs/stacks/clarity/functions/less-than.mdx +++ b/content/docs/stacks/clarity/functions/less-than.mdx @@ -5,7 +5,7 @@ description: Using the less than function for comparisons in Clarity smart contr The less than function (`<`) in Clarity compares two values and returns true if the first value is less than the second. It's a fundamental comparison operation used in many smart contract conditions and logic flows. -## Function Signature +## Function signature ```clarity (< v1 v2) @@ -32,14 +32,14 @@ Use the less than function when you need to: - Create conditional logic based on numerical comparisons. - Sort or order data based on numerical or lexicographical order. -## Best Practices +## Best practices - Ensure that both inputs are of the same type to avoid runtime errors. - Be aware of the differences in comparison between signed (int) and unsigned (uint) integers. - When comparing strings or buffers, understand that the comparison is lexicographical. - Consider edge cases, especially when dealing with the limits of integer ranges. -## Practical Example: Auction Contract with Maximum Bid +## Practical example: Auction contract with maximum bid Let's implement a simple auction contract that uses the less than function to enforce a maximum bid amount: @@ -88,13 +88,13 @@ This example demonstrates: 2. Using `<` to ensure the bid is less than the maximum allowed bid. 3. Combining the less than check with other contract logic for an auction system. -## Common Pitfalls +## Common pitfalls 1. Comparing values of different types, which will result in a runtime error. 2. Not considering the inclusive nature of `<=` vs the exclusive nature of `<` when setting thresholds. 3. Overlooking potential integer underflow when working with very small numbers. -## Related Functions +## Related functions - `>`: Used for greater than comparisons. - `<=`: Used for less than or equal to comparisons. diff --git a/content/docs/stacks/clarity/functions/let.mdx b/content/docs/stacks/clarity/functions/let.mdx index f25a6d0a..5ab01981 100644 --- a/content/docs/stacks/clarity/functions/let.mdx +++ b/content/docs/stacks/clarity/functions/let.mdx @@ -3,7 +3,7 @@ title: let description: Binding variables to expressions in Clarity smart contracts. --- -## Function Signature +## Function signature ```clarity (let ((name1 expr1) (name2 expr2) ...) expr-body1 expr-body2 ... expr-body-last) @@ -30,14 +30,14 @@ Use `let` when you need to: - Improve the readability and maintainability of your code. - Ensure sequential evaluation of expressions. -## Best Practices +## Best practices - Use meaningful variable names for better readability. - Ensure that the expressions are evaluated in the correct order. - Combine with other control flow functions for more complex logic. - Be aware that `let` bindings are sequential and can refer to prior bindings. -## Practical Example: Calculating a Sum +## Practical example: Calculate a sum Let's implement a function that calculates the sum of two numbers using `let`: @@ -60,14 +60,14 @@ This example demonstrates: 2. Returning the sum as the result of the function. 3. Simplifying the function body by breaking it into smaller parts. -## Common Pitfalls +## Common pitfalls 1. Using `let` bindings out of order, leading to incorrect evaluations. 2. Not handling all possible conditions, resulting in incomplete logic. 3. Overlooking the need for proper error handling and validation. 4. Using `let` for simple expressions where it is not necessary. -## Related Functions +## Related functions - `begin`: Evaluates multiple expressions sequentially, returning the last expression's value. - `if`: Implements conditional logic based on boolean expressions. diff --git a/content/docs/stacks/clarity/functions/list.mdx b/content/docs/stacks/clarity/functions/list.mdx index 4fa41ec1..fa4e648f 100644 --- a/content/docs/stacks/clarity/functions/list.mdx +++ b/content/docs/stacks/clarity/functions/list.mdx @@ -3,7 +3,7 @@ title: list description: Constructing lists in Clarity smart contracts. --- -## Function Signature +## Function signature ```clarity (list expr1 expr2 expr3 ...) @@ -30,14 +30,14 @@ Use `list` when you need to: - Pass lists as arguments to functions. - Perform operations on collections of data. -## Best Practices +## Best practices - Ensure all elements in the list are of the same type. - Use meaningful variable names for better readability. - Combine with other list functions for comprehensive list handling. - Be aware of the maximum length of lists in Clarity. -## Practical Example: Creating a List of Integers +## Practical example: Create a list of integers Let's implement a function that creates a list of integers and returns its length: @@ -60,14 +60,14 @@ This example demonstrates: 2. Binding the list to a variable using `let`. 3. Returning the length of the list using `len`. -## Common Pitfalls +## Common pitfalls 1. Using `list` with elements of different types, causing type errors. 2. Assuming the list will always be within a certain length, leading to unhandled cases. 3. Not handling all possible conditions, resulting in incomplete list checks. 4. Overlooking the need for comprehensive validation and error checking. -## Related Functions +## Related functions - `len`: Returns the length of a list. - `append`: Adds an element to the end of a list. diff --git a/content/docs/stacks/clarity/functions/log2.mdx b/content/docs/stacks/clarity/functions/log2.mdx index 37ffe57b..dc54e664 100644 --- a/content/docs/stacks/clarity/functions/log2.mdx +++ b/content/docs/stacks/clarity/functions/log2.mdx @@ -3,7 +3,7 @@ title: log2 description: Calculating the base-2 logarithm of a number in Clarity smart contracts. --- -## Function Signature +## Function signature ```clarity (log2 n) @@ -30,14 +30,14 @@ Use `log2` when you need to: - Determine the power of 2 needed to obtain a given value. - Simplify mathematical operations involving logarithms. -## Best Practices +## Best practices - Ensure the input value is non-negative, as `log2` fails on negative numbers. - Use meaningful variable names for better readability. - Combine with other mathematical functions for comprehensive calculations. - Be aware of the integer rounding behavior of `log2`. -## Practical Example: Calculating Logarithm of a Number +## Practical example: Calculate logarithm of a number Let's implement a function that calculates the base-2 logarithm of a given number: @@ -56,14 +56,14 @@ This example demonstrates: 2. Implementing a read-only function to return the logarithm. 3. Handling both small and large input values. -## Common Pitfalls +## Common pitfalls 1. Using `log2` on negative numbers, causing the function to fail. 2. Assuming the result will always be an integer, leading to incorrect expectations. 3. Not handling all possible conditions, resulting in incomplete calculations. 4. Overlooking the need for proper error handling and validation. -## Related Functions +## Related functions - `sqrti`: Returns the largest integer that is less than or equal to the square root of a number. - `pow`: Raises a number to the power of another number. diff --git a/content/docs/stacks/clarity/functions/map-delete.mdx b/content/docs/stacks/clarity/functions/map-delete.mdx index 4ced6de2..f0adc262 100644 --- a/content/docs/stacks/clarity/functions/map-delete.mdx +++ b/content/docs/stacks/clarity/functions/map-delete.mdx @@ -3,7 +3,7 @@ title: map-delete description: Removing an entry from a map in Clarity smart contracts. --- -## Function Signature +## Function signature ```clarity (map-delete map-name key-tuple) @@ -30,14 +30,14 @@ Use `map-delete` when you need to: - Ensure data integrity by deleting obsolete or incorrect entries. - Maintain clean and accurate data in your smart contract. -## Best Practices +## Best practices - Ensure the key-tuple accurately identifies the entry to be deleted. - Use meaningful variable names for better readability. - Combine with other map functions for comprehensive map management. - Be aware of the performance implications of frequent deletions in large maps. -## Practical Example: Deleting a User's Data +## Practical example: Delete a user's data Let's implement a function that deletes a user's data from a map: @@ -58,14 +58,14 @@ This example demonstrates: 2. Implementing a public function to delete the data. 3. Handling the case where the user's data is present and needs to be removed. -## Common Pitfalls +## Common pitfalls 1. Using `map-delete` with an incorrect key-tuple, causing the deletion to fail. 2. Assuming the entry will always exist, leading to unhandled cases. 3. Not handling all possible conditions, resulting in incomplete data management. 4. Overlooking the need for proper error handling and validation. -## Related Functions +## Related functions - `map-set`: Sets the value associated with a key in a map. - `map-get?`: Retrieves an entry from a map. diff --git a/content/docs/stacks/clarity/functions/map-get.mdx b/content/docs/stacks/clarity/functions/map-get.mdx index 5b299fa7..5a2bde99 100644 --- a/content/docs/stacks/clarity/functions/map-get.mdx +++ b/content/docs/stacks/clarity/functions/map-get.mdx @@ -3,7 +3,7 @@ title: map-get? description: Retrieving an entry from a map in Clarity smart contracts. --- -## Function Signature +## Function signature ```clarity (map-get? map-name key-tuple) @@ -30,14 +30,14 @@ Use `map-get?` when you need to: - Check for the existence of values in a map. - Access stored data in your smart contract. -## Best Practices +## Best practices - Ensure the key-tuple accurately identifies the entry to be retrieved. - Use meaningful variable names for better readability. - Combine with other map functions for comprehensive map management. - Handle the `none` case to avoid runtime errors. -## Practical Example: Retrieving User Data +## Practical example: Retrieve user data Let's implement a function that retrieves a user's data from a map: @@ -59,14 +59,14 @@ This example demonstrates: 2. Implementing a read-only function to return the retrieved data. 3. Handling both the case where the user's data is present and where it is not. -## Common Pitfalls +## Common pitfalls 1. Using `map-get?` with an incorrect key-tuple, causing the retrieval to fail. 2. Assuming the entry will always exist, leading to unhandled `none` cases. 3. Not handling all possible conditions, resulting in incomplete data retrieval. 4. Overlooking the need for proper error handling and validation. -## Related Functions +## Related functions - `map-set`: Sets the value associated with a key in a map. - `map-delete`: Removes an entry from a map. diff --git a/content/docs/stacks/clarity/functions/map-insert.mdx b/content/docs/stacks/clarity/functions/map-insert.mdx index b2982965..1735d395 100644 --- a/content/docs/stacks/clarity/functions/map-insert.mdx +++ b/content/docs/stacks/clarity/functions/map-insert.mdx @@ -3,7 +3,7 @@ title: map-insert description: Inserting an entry into a map in Clarity smart contracts. --- -## Function Signature +## Function signature ```clarity (map-insert map-name key-tuple value-tuple) @@ -30,14 +30,14 @@ Use `map-insert` when you need to: - Manage data in your smart contract. - Create unique key-value pairs in maps. -## Best Practices +## Best practices - Ensure the key-tuple and value-tuple are correctly formatted. - Use meaningful variable names for better readability. - Combine with other map functions for comprehensive map management. - Handle the case where the key already exists to avoid unexpected behavior. -## Practical Example: Inserting User Data +## Practical example: Insert user data Let's implement a function that inserts a user's data into a map: @@ -58,14 +58,14 @@ This example demonstrates: 2. Implementing a public function to insert the data. 3. Handling both the case where the entry is successfully inserted and where it already exists. -## Common Pitfalls +## Common pitfalls 1. Using `map-insert` with incorrectly formatted tuples, causing the insertion to fail. 2. Assuming the entry will always be inserted, leading to unhandled cases. 3. Not handling all possible conditions, resulting in incomplete data management. 4. Overlooking the need for proper error handling and validation. -## Related Functions +## Related functions - `map-set`: Sets the value associated with a key in a map, overwriting any existing value. - `map-delete`: Removes an entry from a map. diff --git a/content/docs/stacks/clarity/functions/map-set.mdx b/content/docs/stacks/clarity/functions/map-set.mdx index 6ded9c2b..5d5eb78a 100644 --- a/content/docs/stacks/clarity/functions/map-set.mdx +++ b/content/docs/stacks/clarity/functions/map-set.mdx @@ -3,7 +3,7 @@ title: map-set description: Setting an entry in a map in Clarity smart contracts. --- -## Function Signature +## Function signature ```clarity (map-set map-name key-tuple value-tuple) @@ -30,14 +30,14 @@ Use `map-set` when you need to: - Ensure data integrity by updating existing entries. - Maintain accurate data in your smart contract. -## Best Practices +## Best practices - Ensure the key-tuple and value-tuple are correctly formatted. - Use meaningful variable names for better readability. - Combine with other map functions for comprehensive map management. - Be aware of the performance implications of frequent updates in large maps. -## Practical Example: Setting User Data +## Practical example: Set user data Let's implement a function that sets a user's data in a map: @@ -58,14 +58,14 @@ This example demonstrates: 2. Implementing a public function to set the data. 3. Handling both the case where the entry is newly created and where it is updated. -## Common Pitfalls +## Common pitfalls 1. Using `map-set` with incorrectly formatted tuples, causing the operation to fail. 2. Assuming the entry will always be updated, leading to unhandled cases. 3. Not handling all possible conditions, resulting in incomplete data management. 4. Overlooking the need for proper error handling and validation. -## Related Functions +## Related functions - `map-insert`: Inserts a value into a map if the key does not already exist. - `map-delete`: Removes an entry from a map. diff --git a/content/docs/stacks/clarity/functions/map.mdx b/content/docs/stacks/clarity/functions/map.mdx index 4d32d8f2..14ab6b51 100644 --- a/content/docs/stacks/clarity/functions/map.mdx +++ b/content/docs/stacks/clarity/functions/map.mdx @@ -3,7 +3,7 @@ title: map description: Applying a function to each element of a list in Clarity smart contracts. --- -## Function Signature +## Function signature ```clarity (map function list) @@ -30,14 +30,14 @@ Use `map` when you need to: - Perform bulk operations on lists. - Simplify and abstract repetitive operations on list elements. -## Best Practices +## Best practices - Ensure the function being applied is compatible with the elements of the list. - Use meaningful variable names for better readability. - Combine with other list functions for comprehensive list handling. - Be aware of the performance implications of applying functions to large lists. -## Practical Example: Doubling Each Element in a List +## Practical example: Double each element in a list Let's implement a function that doubles each element in a list of integers: @@ -60,14 +60,14 @@ This example demonstrates: 3. Implementing a read-only function to return the transformed list. 4. Handling both small and large input lists. -## Common Pitfalls +## Common pitfalls 1. Using `map` with incompatible function and list element types, causing type errors. 2. Assuming the list will always be within a certain length, leading to unhandled cases. 3. Not handling all possible conditions, resulting in incomplete list transformations. 4. Overlooking the need for proper error handling and validation. -## Related Functions +## Related functions - `filter`: Filters elements of a list based on a predicate function. - `fold`: Reduces a list to a single value by applying a function. diff --git a/content/docs/stacks/clarity/functions/match.mdx b/content/docs/stacks/clarity/functions/match.mdx index 84029d7b..fb24d23d 100644 --- a/content/docs/stacks/clarity/functions/match.mdx +++ b/content/docs/stacks/clarity/functions/match.mdx @@ -3,7 +3,7 @@ title: match description: Handling different branches or cases in Clarity smart contracts. --- -## Function Signature +## Function signature ```clarity (match opt-input some-binding-name some-branch none-branch) @@ -31,14 +31,14 @@ Use `match` when you need to: - Enhance the readability and maintainability of your code. - Ensure comprehensive handling of all possible cases. -## Best Practices +## Best practices - Ensure all possible branches are covered to avoid unhandled cases. - Use meaningful variable names for better readability. - Combine with other control flow functions for more complex logic. - Be aware of the performance implications of extensive branching. -## Practical Example: Handling Optional and Response Values +## Practical example: Handle optional and response values Let's implement functions that handle optional and response values using `match`: @@ -67,14 +67,14 @@ This example demonstrates: 2. Using `match` to handle the result of a response value. 3. Implementing functions to return the appropriate result based on the input type. -## Common Pitfalls +## Common pitfalls 1. Using `match` without covering all possible branches, leading to unhandled cases. 2. Assuming the value will always match a certain branch, causing runtime errors. 3. Not handling all possible conditions, resulting in incomplete logic. 4. Overlooking the need for proper error handling and validation. -## Related Functions +## Related functions - `if`: Implements conditional logic based on boolean expressions. - `let`: Binds variables to expressions within a local scope. diff --git a/content/docs/stacks/clarity/functions/merge.mdx b/content/docs/stacks/clarity/functions/merge.mdx index 0162aab2..e791d77c 100644 --- a/content/docs/stacks/clarity/functions/merge.mdx +++ b/content/docs/stacks/clarity/functions/merge.mdx @@ -3,7 +3,7 @@ title: merge description: Merging tuples in Clarity smart contracts. --- -## Function Signature +## Function signature ```clarity (merge tuple1 tuple2) @@ -30,14 +30,14 @@ Use `merge` when you need to: - Ensure data integrity by creating new tuples without mutating the original ones. - Simplify and abstract tuple merging operations. -## Best Practices +## Best practices - Ensure the tuples being merged have compatible fields. - Use meaningful variable names for better readability. - Combine with other tuple and map functions for comprehensive data management. - Be aware of the performance implications of frequent tuple merging in large data structures. -## Practical Example: Merging User Data +## Practical example: Merge user data Let's implement a function that merges additional data into a user's existing data: @@ -65,14 +65,14 @@ This example demonstrates: 2. Implementing a public function to update the user's address. 3. Handling both the retrieval and updating of user data in a clean and efficient manner. -## Common Pitfalls +## Common pitfalls 1. Using `merge` with tuples that have incompatible fields, causing runtime errors. 2. Assuming the tuples will always have the expected fields, leading to unhandled cases. 3. Not handling all possible conditions, resulting in incomplete data management. 4. Overlooking the need for proper error handling and validation. -## Related Functions +## Related functions - `map-set`: Sets the value associated with a key in a map. - `map-get?`: Retrieves an entry from a map. diff --git a/content/docs/stacks/clarity/functions/mod.mdx b/content/docs/stacks/clarity/functions/mod.mdx index efe7a4d9..4cfd1a74 100644 --- a/content/docs/stacks/clarity/functions/mod.mdx +++ b/content/docs/stacks/clarity/functions/mod.mdx @@ -3,7 +3,7 @@ title: mod description: Calculating the remainder of integer division in Clarity smart contracts. --- -## Function Signature +## Function signature ```clarity (mod i1 i2) @@ -30,14 +30,14 @@ Use `mod` when you need to: - Perform operations that require remainders. - Simplify and abstract modular operations. -## Best Practices +## Best practices - Ensure the divisor is not zero to avoid runtime errors. - Use meaningful variable names for better readability. - Combine with other mathematical functions for comprehensive calculations. - Be aware of the performance implications of frequent modular operations. -## Practical Example: Calculating Remainders +## Practical example: Calculate remainders Let's implement a function that calculates the remainder of dividing two numbers: @@ -57,14 +57,14 @@ This example demonstrates: 2. Implementing a read-only function to return the remainder. 3. Handling both small and large input values. -## Common Pitfalls +## Common pitfalls 1. Using `mod` with a divisor of zero, causing a runtime error. 2. Assuming the result will always be positive, leading to incorrect expectations. 3. Not handling all possible conditions, resulting in incomplete calculations. 4. Overlooking the need for proper error handling and validation. -## Related Functions +## Related functions - `+`: Adds two numbers. - `-`: Subtracts one number from another. diff --git a/content/docs/stacks/clarity/functions/multiply.mdx b/content/docs/stacks/clarity/functions/multiply.mdx index 29ba7829..ccaf9ac8 100644 --- a/content/docs/stacks/clarity/functions/multiply.mdx +++ b/content/docs/stacks/clarity/functions/multiply.mdx @@ -5,7 +5,7 @@ description: Using the multiplication function for arithmetic operations in Clar The multiplication function (`*`) in Clarity performs multiplication on a variable number of integer inputs. It's a fundamental arithmetic operation used in many smart contract calculations. -## Function Signature +## Function signature ```clarity (* i1 i2...) @@ -32,14 +32,14 @@ Use the multiplication function when you need to: - Calculate compound values or rates. - Implement mathematical formulas that involve multiplication. -## Best Practices +## Best practices - Always consider the possibility of overflow when multiplying large numbers. - Use appropriate types (int or uint) based on your needs and expected value ranges. - Consider using `mul-overflow?` for checked multiplication if overflow detection is needed. - Be aware that multiplying by zero will always return zero. -## Practical Example: Token Vesting Contract +## Practical example: Token vesting contract Let's implement a simple token vesting contract that uses multiplication to calculate vested amounts: @@ -95,13 +95,13 @@ This example demonstrates: 2. Combining multiplication with division to implement a linear vesting schedule. 3. Using multiplication as part of a larger mathematical formula in a smart contract context. -## Common Pitfalls +## Common pitfalls 1. Overlooking potential overflow when multiplying large numbers. 2. Not considering the effect of integer division when combined with multiplication. 3. Assuming multiplication always increases a value (forgetting about multiplication by fractions < 1 in integer arithmetic). -## Related Functions +## Related functions - `/`: Used for division operations. - `+`: Used for addition operations. diff --git a/content/docs/stacks/clarity/functions/nft-burn.mdx b/content/docs/stacks/clarity/functions/nft-burn.mdx index 23fdcebd..4abe6799 100644 --- a/content/docs/stacks/clarity/functions/nft-burn.mdx +++ b/content/docs/stacks/clarity/functions/nft-burn.mdx @@ -3,7 +3,7 @@ title: nft-burn? description: Burning a non-fungible token (NFT) in Clarity smart contracts. --- -## Function Signature +## Function signature ```clarity (nft-burn? asset-class asset-identifier sender) @@ -30,14 +30,14 @@ Use `nft-burn?` when you need to: - Remove ownership records of burned NFTs. - Handle NFT burn operations in your smart contract. -## Best Practices +## Best practices - Ensure the `sender` principal owns the NFT before attempting to burn it. - Use meaningful variable names for better readability. - Combine with other NFT functions for comprehensive NFT management. - Handle the possible error cases to ensure robust contract behavior. -## Practical Example: Burning an NFT +## Practical example: Burn an NFT Let's implement a function that burns an NFT owned by the sender: @@ -59,14 +59,14 @@ This example demonstrates: 2. Implementing a public function to handle the burn operation. 3. Handling both the successful burn and the case where the asset no longer exists. -## Common Pitfalls +## Common pitfalls 1. Using `nft-burn?` without ensuring the `sender` owns the NFT, causing the operation to fail. 2. Assuming the NFT will always exist, leading to unhandled error cases. 3. Not handling all possible conditions, resulting in incomplete NFT management. 4. Overlooking the need for proper error handling and validation. -## Related Functions +## Related functions - `nft-mint?`: Mints a new non-fungible token. - `nft-transfer?`: Transfers ownership of a non-fungible token. diff --git a/content/docs/stacks/clarity/functions/nft-get-owner.mdx b/content/docs/stacks/clarity/functions/nft-get-owner.mdx index f843fd87..f067b5da 100644 --- a/content/docs/stacks/clarity/functions/nft-get-owner.mdx +++ b/content/docs/stacks/clarity/functions/nft-get-owner.mdx @@ -3,7 +3,7 @@ title: nft-get-owner? description: Retrieving the owner of a non-fungible token (NFT) in Clarity smart contracts. --- -## Function Signature +## Function signature ```clarity (nft-get-owner? asset-class asset-identifier) @@ -30,14 +30,14 @@ Use `nft-get-owner?` when you need to: - Verify ownership records in your smart contract. - Access ownership information for NFTs. -## Best Practices +## Best practices - Ensure the `asset-identifier` is correctly formatted and exists. - Use meaningful variable names for better readability. - Combine with other NFT functions for comprehensive NFT management. - Handle the `none` case to avoid runtime errors. -## Practical Example: Retrieving NFT Owner +## Practical example: Retrieve NFT owner Let's implement a function that retrieves the owner of an NFT: @@ -59,14 +59,14 @@ This example demonstrates: 2. Implementing a read-only function to return the owner's principal. 3. Handling both the case where the NFT exists and where it does not. -## Common Pitfalls +## Common pitfalls 1. Using `nft-get-owner?` with an incorrect or non-existent `asset-identifier`, causing the function to return `none`. 2. Assuming the NFT will always exist, leading to unhandled `none` cases. 3. Not handling all possible conditions, resulting in incomplete ownership checks. 4. Overlooking the need for proper error handling and validation. -## Related Functions +## Related functions - `nft-mint?`: Mints a new non-fungible token. - `nft-transfer?`: Transfers ownership of a non-fungible token. diff --git a/content/docs/stacks/clarity/functions/nft-mint.mdx b/content/docs/stacks/clarity/functions/nft-mint.mdx index 23698835..95f0698e 100644 --- a/content/docs/stacks/clarity/functions/nft-mint.mdx +++ b/content/docs/stacks/clarity/functions/nft-mint.mdx @@ -3,7 +3,7 @@ title: nft-mint? description: Minting a non-fungible token (NFT) in Clarity smart contracts. --- -## Function Signature +## Function signature ```clarity (nft-mint? asset-class asset-identifier recipient) @@ -30,14 +30,14 @@ Use `nft-mint?` when you need to: - Prevent duplicate NFT creation. - Handle NFT minting operations in your smart contract. -## Best Practices +## Best practices - Ensure the `asset-identifier` is unique and correctly formatted. - Use meaningful variable names for better readability. - Combine with other NFT functions for comprehensive NFT management. - Handle the possible error cases to ensure robust contract behavior. -## Practical Example: Minting an NFT +## Practical example: Mint an NFT Let's implement a function that mints a new NFT and assigns it to the recipient: @@ -58,14 +58,14 @@ This example demonstrates: 2. Implementing a public function to handle the minting operation. 3. Handling both the successful mint and the case where the asset already exists. -## Common Pitfalls +## Common pitfalls 1. Using `nft-mint?` with a non-unique `asset-identifier`, causing the operation to fail. 2. Assuming the NFT will always be minted, leading to unhandled error cases. 3. Not handling all possible conditions, resulting in incomplete NFT management. 4. Overlooking the need for proper error handling and validation. -## Related Functions +## Related functions - `nft-get-owner?`: Retrieves the owner of a non-fungible token. - `nft-transfer?`: Transfers ownership of a non-fungible token. diff --git a/content/docs/stacks/clarity/functions/nft-transfer.mdx b/content/docs/stacks/clarity/functions/nft-transfer.mdx index 5ed7b18a..b13116d4 100644 --- a/content/docs/stacks/clarity/functions/nft-transfer.mdx +++ b/content/docs/stacks/clarity/functions/nft-transfer.mdx @@ -3,7 +3,7 @@ title: nft-transfer? description: Transferring ownership of a non-fungible token (NFT) in Clarity smart contracts. --- -## Function Signature +## Function signature ```clarity (nft-transfer? asset-class asset-identifier sender recipient) @@ -30,7 +30,7 @@ Use `nft-transfer?` when you need to: - Update ownership records in your smart contract. - Handle NFT transfer operations. -## Best Practices +## Best practices - Ensure the `sender` principal owns the NFT before attempting to transfer it. - Ensure the `sender` and `recipient` are different principals. @@ -38,7 +38,7 @@ Use `nft-transfer?` when you need to: - Combine with other NFT functions for comprehensive NFT management. - Handle the possible error cases to ensure robust contract behavior. -## Practical Example: Transferring an NFT +## Practical example: Transfer an NFT Let's implement a function that transfers an NFT from the sender to the recipient: @@ -62,14 +62,14 @@ This example demonstrates: 3. Handling both the successful transfer and the case where the sender no longer owns the asset. 4. Handling the case where the asset does not exist. -## Common Pitfalls +## Common pitfalls 1. Using `nft-transfer?` without ensuring the `sender` owns the NFT, causing the operation to fail. 2. Assuming the `sender` and `recipient` are the same principal, leading to an invalid transfer. 3. Not handling all possible conditions, resulting in incomplete NFT management. 4. Overlooking the need for proper error handling and validation. -## Related Functions +## Related functions - `nft-mint?`: Mints a new non-fungible token. - `nft-get-owner?`: Retrieves the owner of a non-fungible token. diff --git a/content/docs/stacks/clarity/functions/not.mdx b/content/docs/stacks/clarity/functions/not.mdx index 841a47fa..6c031b62 100644 --- a/content/docs/stacks/clarity/functions/not.mdx +++ b/content/docs/stacks/clarity/functions/not.mdx @@ -3,7 +3,7 @@ title: not description: Logical negation in Clarity smart contracts. --- -## Function Signature +## Function signature ```clarity (not boolean-expression) @@ -28,14 +28,14 @@ Use `not` when you need to: - Implement logical negation in conditional statements. - Simplify and abstract the process of inverting boolean values. -## Best Practices +## Best practices - Ensure the input is a boolean expression. - Use meaningful variable names for better readability. - Combine with other logical functions for comprehensive boolean logic. - Be aware of the performance implications of complex logical operations. -## Practical Example: Inverting a Boolean Expression +## Practical example: Invert a boolean expression Let's implement a function that checks if a number is not zero: @@ -54,14 +54,14 @@ This example demonstrates: 2. Implementing a read-only function to check if a number is not zero. 3. Handling both true and false cases. -## Common Pitfalls +## Common pitfalls 1. Using `not` with non-boolean expressions, causing type errors. 2. Assuming the result will always be true or false, leading to incorrect logic. 3. Not handling all possible conditions, resulting in incomplete boolean logic. 4. Overlooking the need for proper error handling and validation. -## Related Functions +## Related functions - `and`: Logical conjunction of multiple boolean expressions. - `or`: Logical disjunction of multiple boolean expressions. diff --git a/content/docs/stacks/clarity/functions/ok.mdx b/content/docs/stacks/clarity/functions/ok.mdx index 56362573..c89aed38 100644 --- a/content/docs/stacks/clarity/functions/ok.mdx +++ b/content/docs/stacks/clarity/functions/ok.mdx @@ -3,7 +3,7 @@ title: ok description: Constructing a successful response type in Clarity smart contracts. --- -## Function Signature +## Function signature ```clarity (ok value) @@ -30,14 +30,14 @@ Use `ok` when you need to: - Clearly distinguish between success and error states. - Handle function return values in your smart contract. -## Best Practices +## Best practices - Ensure the value passed to `ok` is the intended successful result. - Use meaningful variable names for better readability. - Combine with `err` for comprehensive response handling. - Handle the possible error cases to ensure robust contract behavior. -## Practical Example: Returning a Successful Response +## Practical example: Return a successful response Let's implement a function that returns a successful response with a value: @@ -55,14 +55,14 @@ This example demonstrates: 2. Implementing a read-only function to return a successful response. 3. Handling the successful response case. -## Common Pitfalls +## Common pitfalls 1. Using `ok` with an incorrect or invalid value, causing unexpected behavior. 2. Assuming the response will always be successful, leading to unhandled error cases. 3. Not handling all possible conditions, resulting in incomplete response handling. 4. Overlooking the need for proper error handling and validation. -## Related Functions +## Related functions - `err`: Constructs an error response type. - `match`: Handles different branches or cases for optional and response types. diff --git a/content/docs/stacks/clarity/functions/or.mdx b/content/docs/stacks/clarity/functions/or.mdx index 53771981..81ef6cb8 100644 --- a/content/docs/stacks/clarity/functions/or.mdx +++ b/content/docs/stacks/clarity/functions/or.mdx @@ -3,7 +3,7 @@ title: or description: Logical disjunction in Clarity smart contracts. --- -## Function Signature +## Function signature ```clarity (or b1 b2 ...) @@ -28,14 +28,14 @@ Use `or` when you need to: - Implement logical disjunction in conditional statements. - Simplify and abstract the process of evaluating multiple boolean values. -## Best Practices +## Best practices - Ensure all inputs are boolean expressions. - Use meaningful variable names for better readability. - Combine with other logical functions for comprehensive boolean logic. - Be aware of the performance implications of complex logical operations. -## Practical Example: Evaluating Multiple Conditions +## Practical example: Evaluate multiple conditions Let's implement a function that checks if a number is either zero or negative: @@ -55,14 +55,14 @@ This example demonstrates: 2. Implementing a read-only function to check if a number is either zero or negative. 3. Handling both true and false cases. -## Common Pitfalls +## Common pitfalls 1. Using `or` with non-boolean expressions, causing type errors. 2. Assuming the result will always be true or false, leading to incorrect logic. 3. Not handling all possible conditions, resulting in incomplete boolean logic. 4. Overlooking the need for proper error handling and validation. -## Related Functions +## Related functions - `and`: Logical conjunction of multiple boolean expressions. - `not`: Logical negation of a boolean expression. diff --git a/content/docs/stacks/clarity/functions/pow.mdx b/content/docs/stacks/clarity/functions/pow.mdx index 211b51e4..b08d0ff6 100644 --- a/content/docs/stacks/clarity/functions/pow.mdx +++ b/content/docs/stacks/clarity/functions/pow.mdx @@ -3,7 +3,7 @@ title: pow description: Calculating the power of a number in Clarity smart contracts. --- -## Function Signature +## Function signature ```clarity (pow base exponent) @@ -30,14 +30,14 @@ Use `pow` when you need to: - Raise numbers to a power. - Simplify and abstract exponentiation operations. -## Best Practices +## Best practices - Ensure the base and exponent are correctly formatted and within acceptable ranges. - Use meaningful variable names for better readability. - Combine with other mathematical functions for comprehensive calculations. - Be aware of the performance implications of large exponentiation operations. -## Practical Example: Calculating Token Balances in Decimal Format +## Practical example: Calculate token balances in decimal format Let's implement a function that calculates the power of a number, specifically for converting integer representations of tokens or uStx: @@ -58,14 +58,14 @@ This example demonstrates: 2. Implementing a read-only function to calculate the total balance in decimal format. 3. Handling balances from different versions of a token contract. -## Common Pitfalls +## Common pitfalls 1. Using `pow` with negative exponents, which is not supported and will cause a runtime error. 2. Assuming the result will always be within acceptable ranges, leading to overflow errors. 3. Not handling all possible conditions, resulting in incomplete calculations. 4. Overlooking the need for proper error handling and validation. -## Related Functions +## Related functions - `*`: Multiplies two or more numbers. - `+`: Adds two or more numbers. diff --git a/content/docs/stacks/clarity/functions/principal-construct.mdx b/content/docs/stacks/clarity/functions/principal-construct.mdx index 62d3e429..54e0ad5d 100644 --- a/content/docs/stacks/clarity/functions/principal-construct.mdx +++ b/content/docs/stacks/clarity/functions/principal-construct.mdx @@ -3,7 +3,7 @@ title: principal-construct? description: Constructing a principal in Clarity smart contracts. --- -## Function Signature +## Function signature ```clarity (principal-construct? version-byte hash-bytes [contract-name]) @@ -30,14 +30,14 @@ Use `principal-construct?` when you need to: - Validate the construction of principals. - Handle principal creation operations. -## Best Practices +## Best practices - Ensure the `version-byte` and `hash-bytes` are correctly formatted. - Use meaningful variable names for better readability. - Combine with other principal functions for comprehensive identity management. - Handle the possible error cases to ensure robust contract behavior. -## Practical Example: Constructing a Principal +## Practical example: Construct a principal Let's implement a function that constructs a standard principal: @@ -55,14 +55,14 @@ This example demonstrates: 2. Implementing a public function to handle the principal construction. 3. Handling both successful and error cases. -## Common Pitfalls +## Common pitfalls 1. Using `principal-construct?` with incorrectly formatted `versionByte` or `hashBytes`, causing the operation to fail. 2. Assuming the principal will always be valid, leading to unhandled error cases. 3. Not handling all possible conditions, resulting in incomplete principal management. 4. Overlooking the need for proper error handling and validation. -## Related Functions +## Related functions - `principal-of?`: Returns the principal derived from a public key. - `contract-caller`: Returns the caller of the current contract context. diff --git a/content/docs/stacks/clarity/functions/principal-destruct.mdx b/content/docs/stacks/clarity/functions/principal-destruct.mdx index bb86a7b3..9ea5bbfb 100644 --- a/content/docs/stacks/clarity/functions/principal-destruct.mdx +++ b/content/docs/stacks/clarity/functions/principal-destruct.mdx @@ -3,7 +3,7 @@ title: principal-destruct? description: Decomposing a principal into its components in Clarity smart contracts. --- -## Function Signature +## Function signature ```clarity (principal-destruct? principal-address) @@ -30,14 +30,14 @@ Use `principal-destruct?` when you need to: - Validate the components of a principal. - Handle principal decomposition operations. -## Best Practices +## Best practices - Ensure the `principal` is correctly formatted. - Use meaningful variable names for better readability. - Combine with other principal functions for comprehensive identity management. - Handle the possible error cases to ensure robust contract behavior. -## Practical Example: Decomposing a Principal +## Practical example: Deconstruct a principal Let's implement a function that destructs a principal back into its components: @@ -58,14 +58,14 @@ This example demonstrates: 2. Implementing a public function to handle the principal decomposition. 3. Handling both successful and error cases. -## Common Pitfalls +## Common pitfalls 1. Using `principal-destruct?` with incorrectly formatted principals, causing the operation to fail. 2. Assuming the principal will always be valid, leading to unhandled error cases. 3. Not handling all possible conditions, resulting in incomplete principal management. 4. Overlooking the need for proper error handling and validation. -## Related Functions +## Related functions - `principal-construct?`: Constructs a principal from its components. - `principal-of?`: Returns the principal derived from a public key. diff --git a/content/docs/stacks/clarity/functions/principal-of.mdx b/content/docs/stacks/clarity/functions/principal-of.mdx index 900d5cf1..015f5ee1 100644 --- a/content/docs/stacks/clarity/functions/principal-of.mdx +++ b/content/docs/stacks/clarity/functions/principal-of.mdx @@ -3,7 +3,7 @@ title: principal-of? description: Deriving a principal from a public key in Clarity smart contracts. --- -## Function Signature +## Function signature ```clarity (principal-of? public-key) @@ -30,14 +30,14 @@ Use `principal-of?` when you need to: - Validate the conversion of a public key to a principal. - Handle principal derivation operations. -## Best Practices +## Best practices - Ensure the `public-key` is correctly formatted and valid. - Use meaningful variable names for better readability. - Combine with other principal functions for comprehensive identity management. - Handle the possible error cases to ensure robust contract behavior. -## Practical Example: Deriving a Principal +## Practical example: Derive a principal Let's implement a function that derives a principal from a public key: @@ -55,14 +55,14 @@ This example demonstrates: 2. Implementing a public function to handle the principal derivation. 3. Handling both successful and error cases. -## Common Pitfalls +## Common pitfalls 1. Using `principal-of?` with an incorrectly formatted or invalid `public-key`, causing the operation to fail. 2. Assuming the principal will always be valid, leading to unhandled error cases. 3. Not handling all possible conditions, resulting in incomplete principal management. 4. Overlooking the need for proper error handling and validation. -## Related Functions +## Related functions - `principal-construct?`: Constructs a principal from its components. - `principal-destruct?`: Decomposes a principal into its components. diff --git a/content/docs/stacks/clarity/functions/print.mdx b/content/docs/stacks/clarity/functions/print.mdx index dd802056..2ae61d3f 100644 --- a/content/docs/stacks/clarity/functions/print.mdx +++ b/content/docs/stacks/clarity/functions/print.mdx @@ -3,7 +3,7 @@ title: print description: Evaluating and printing expressions in Clarity smart contracts. --- -## Function Signature +## Function signature ```clarity (print expr) @@ -28,13 +28,13 @@ Use `print` when you need to: - Evaluate and return an input expression. - Output intermediate values for better understanding of contract behavior. -## Best Practices +## Best practices - Use `print` primarily for debugging and development purposes. - Ensure that the expression passed to `print` is meaningful and necessary for debugging. - Remove or comment out `print` statements in production code to avoid unnecessary output. -## Practical Example: Printing an Expression +## Practical example: Print an expression Let's implement a function that prints the result of an addition operation: @@ -53,13 +53,13 @@ This example demonstrates: 2. Implementing a public function to handle the addition and printing. 3. Handling both small and large input values. -## Common Pitfalls +## Common pitfalls 1. Using `print` excessively, leading to cluttered output and reduced readability. 2. Assuming `print` is necessary for all expressions, leading to overuse. 3. Not removing or commenting out `print` statements in production code, resulting in unnecessary output. -## Related Functions +## Related functions - `+`: Adds two or more numbers. - `-`: Subtracts one number from another. diff --git a/content/docs/stacks/clarity/functions/replace-at.mdx b/content/docs/stacks/clarity/functions/replace-at.mdx index cd7d828d..d5cffc42 100644 --- a/content/docs/stacks/clarity/functions/replace-at.mdx +++ b/content/docs/stacks/clarity/functions/replace-at.mdx @@ -3,7 +3,7 @@ title: replace-at? description: Replacing an element at a specific index in a sequence in Clarity smart contracts. --- -## Function Signature +## Function signature ```clarity (replace-at? sequence index new-element) @@ -30,14 +30,14 @@ Use `replace-at?` when you need to: - Validate the index and element replacement in your smart contract. - Handle sequence modification operations. -## Best Practices +## Best practices - Ensure the `index` is within the bounds of the sequence. - Use meaningful variable names for better readability. - Combine with other sequence functions for comprehensive sequence management. - Handle the possible error cases to ensure robust contract behavior. -## Practical Example: Replacing an Element in a List +## Practical example: Replace an element in a list Let's implement a function that replaces an element in a list at a specific index: @@ -56,14 +56,14 @@ This example demonstrates: 2. Implementing a public function to handle the element replacement. 3. Handling both successful and error cases. -## Common Pitfalls +## Common pitfalls 1. Using `replace-at?` with an index that is out of bounds, causing the operation to fail. 2. Assuming the sequence will always be valid, leading to unhandled error cases. 3. Not handling all possible conditions, resulting in incomplete sequence management. 4. Overlooking the need for proper error handling and validation. -## Related Functions +## Related functions - `append`: Adds an element to the end of a list. - `index-of?`: Returns the first index at which an item can be found in a sequence. diff --git a/content/docs/stacks/clarity/functions/secp256k1-recover.mdx b/content/docs/stacks/clarity/functions/secp256k1-recover.mdx index 3851e204..4e7fe2d7 100644 --- a/content/docs/stacks/clarity/functions/secp256k1-recover.mdx +++ b/content/docs/stacks/clarity/functions/secp256k1-recover.mdx @@ -3,7 +3,7 @@ title: secp256k1-recover? description: Recovering the public key from a message hash and signature in Clarity smart contracts. --- -## Function Signature +## Function signature ```clarity (secp256k1-recover? message-hash signature) @@ -30,14 +30,14 @@ Use `secp256k1-recover?` when you need to: - Validate signatures to ensure data integrity. - Handle cryptographic operations. -## Best Practices +## Best practices - Ensure the `message-hash` and `signature` are correctly formatted and valid. - Use meaningful variable names for better readability. - Combine with other cryptographic functions for comprehensive security management. - Handle the possible error cases to ensure robust contract behavior. -## Practical Example: Recovering a Public Key +## Practical example: Recover a public key Let's implement a function that recovers the public key from a message hash and signature: @@ -56,14 +56,14 @@ This example demonstrates: 2. Implementing a public function to handle the public key recovery. 3. Handling both successful and error cases. -## Common Pitfalls +## Common pitfalls 1. Using `secp256k1-recover?` with incorrectly formatted or invalid `message-hash` or `signature`, causing the operation to fail. 2. Assuming the public key will always be valid, leading to unhandled error cases. 3. Not handling all possible conditions, resulting in incomplete cryptographic verification. 4. Overlooking the need for proper error handling and validation. -## Related Functions +## Related functions - `principal-of?`: Returns the principal derived from a public key. - `hash160`: Computes the RIPEMD-160 hash of the SHA-256 hash of the input. diff --git a/content/docs/stacks/clarity/functions/secp256k1-verify.mdx b/content/docs/stacks/clarity/functions/secp256k1-verify.mdx index 4f7b11c7..29f6b239 100644 --- a/content/docs/stacks/clarity/functions/secp256k1-verify.mdx +++ b/content/docs/stacks/clarity/functions/secp256k1-verify.mdx @@ -3,7 +3,7 @@ title: secp256k1-verify description: Verifying a signature against a message hash and public key in Clarity smart contracts. --- -## Function Signature +## Function signature ```clarity (secp256k1-verify message-hash signature public-key) @@ -30,14 +30,14 @@ Use `secp256k1-verify` when you need to: - Validate signatures to ensure data integrity. - Handle cryptographic operations. -## Best Practices +## Best practices - Ensure the `message-hash`, `signature`, and `public-key` are correctly formatted and valid. - Use meaningful variable names for better readability. - Combine with other cryptographic functions for comprehensive security management. - Handle the possible error cases to ensure robust contract behavior. -## Practical Example: Verifying a Signature +## Practical example: Verify a signature Let's implement a function that verifies a signature against a message hash and public key: @@ -56,14 +56,14 @@ This example demonstrates: 2. Implementing a public function to handle the signature verification. 3. Handling both successful and error cases. -## Common Pitfalls +## Common pitfalls 1. Using `secp256k1-verify` with incorrectly formatted or invalid `message-hash`, `signature`, or `public-key`, causing the operation to fail. 2. Assuming the verification will always succeed, leading to unhandled error cases. 3. Not handling all possible conditions, resulting in incomplete cryptographic verification. 4. Overlooking the need for proper error handling and validation. -## Related Functions +## Related functions - `secp256k1-recover?`: Recovers the public key from a message hash and signature. - `sha256`: Computes the SHA-256 hash of the input. diff --git a/content/docs/stacks/clarity/functions/sha256.mdx b/content/docs/stacks/clarity/functions/sha256.mdx index 248b7053..d4d314b7 100644 --- a/content/docs/stacks/clarity/functions/sha256.mdx +++ b/content/docs/stacks/clarity/functions/sha256.mdx @@ -3,7 +3,7 @@ title: sha256 description: Computing the SHA-256 hash of a value in Clarity smart contracts. --- -## Function Signature +## Function signature ```clarity (sha256 value) @@ -30,14 +30,14 @@ Use `sha256` when you need to: - Generate unique hashes to ensure data integrity. - Handle cryptographic hashing operations. -## Best Practices +## Best practices - Ensure the input value is correctly formatted and valid. - Use meaningful variable names for better readability. - Combine with other cryptographic functions for comprehensive security management. - Handle the possible error cases to ensure robust contract behavior. -## Practical Example: Computing a SHA-256 Hash +## Practical example: Compute a SHA-256 hash Let's implement a function that computes the SHA-256 hash of a given buffer: @@ -56,14 +56,14 @@ This example demonstrates: 2. Implementing a public function to handle the hash computation. 3. Handling both successful and error cases. -## Common Pitfalls +## Common pitfalls 1. Using `sha256` with incorrectly formatted or invalid input values, causing the operation to fail. 2. Assuming the hash will always be valid, leading to unhandled error cases. 3. Not handling all possible conditions, resulting in incomplete cryptographic hashing. 4. Overlooking the need for proper error handling and validation. -## Related Functions +## Related functions - `sha512`: Computes the SHA-512 hash of the input. - `sha512/256`: Computes the SHA-512/256 hash of the input. diff --git a/content/docs/stacks/clarity/functions/sha512-256.mdx b/content/docs/stacks/clarity/functions/sha512-256.mdx index 04297ee0..eec4380e 100644 --- a/content/docs/stacks/clarity/functions/sha512-256.mdx +++ b/content/docs/stacks/clarity/functions/sha512-256.mdx @@ -3,7 +3,7 @@ title: sha512/256 description: Computing the SHA-512/256 hash of a value in Clarity smart contracts. --- -## Function Signature +## Function signature ```clarity (sha512/256 value) @@ -30,14 +30,14 @@ Use `sha512/256` when you need to: - Generate unique hashes to ensure data integrity. - Handle cryptographic hashing operations. -## Best Practices +## Best practices - Ensure the input value is correctly formatted and valid. - Use meaningful variable names for better readability. - Combine with other cryptographic functions for comprehensive security management. - Handle the possible error cases to ensure robust contract behavior. -## Practical Example: Computing a SHA-512/256 Hash +## Practical example: Compute a SHA-512/256 hash Let's implement a function that computes the SHA-512/256 hash of a given buffer: @@ -56,14 +56,14 @@ This example demonstrates: 2. Implementing a public function to handle the hash computation. 3. Handling both successful and error cases. -## Common Pitfalls +## Common pitfalls 1. Using `sha512/256` with incorrectly formatted or invalid input values, causing the operation to fail. 2. Assuming the hash will always be valid, leading to unhandled error cases. 3. Not handling all possible conditions, resulting in incomplete cryptographic hashing. 4. Overlooking the need for proper error handling and validation. -## Related Functions +## Related functions - `sha256`: Computes the SHA-256 hash of the input. - `sha512`: Computes the SHA-512 hash of the input. diff --git a/content/docs/stacks/clarity/functions/sha512.mdx b/content/docs/stacks/clarity/functions/sha512.mdx index f3c7d4cb..79147d57 100644 --- a/content/docs/stacks/clarity/functions/sha512.mdx +++ b/content/docs/stacks/clarity/functions/sha512.mdx @@ -3,7 +3,7 @@ title: sha512 description: Computing the SHA-512 hash of a value in Clarity smart contracts. --- -## Function Signature +## Function signature ```clarity (sha512 value) @@ -30,14 +30,14 @@ Use `sha512` when you need to: - Generate unique hashes to ensure data integrity. - Handle cryptographic hashing operations. -## Best Practices +## Best practices - Ensure the input value is correctly formatted and valid. - Use meaningful variable names for better readability. - Combine with other cryptographic functions for comprehensive security management. - Handle the possible error cases to ensure robust contract behavior. -## Practical Example: Computing a SHA-512 Hash +## Practical example: Compute a SHA-512 hash Let's implement a function that computes the SHA-512 hash of a given buffer: @@ -56,14 +56,14 @@ This example demonstrates: 2. Implementing a public function to handle the hash computation. 3. Handling both successful and error cases. -## Common Pitfalls +## Common pitfalls 1. Using `sha512` with incorrectly formatted or invalid input values, causing the operation to fail. 2. Assuming the hash will always be valid, leading to unhandled error cases. 3. Not handling all possible conditions, resulting in incomplete cryptographic hashing. 4. Overlooking the need for proper error handling and validation. -## Related Functions +## Related functions - `sha256`: Computes the SHA-256 hash of the input. - `sha512/256`: Computes the SHA-512/256 hash of the input. diff --git a/content/docs/stacks/clarity/functions/slice.mdx b/content/docs/stacks/clarity/functions/slice.mdx index 77a4f98f..2e848374 100644 --- a/content/docs/stacks/clarity/functions/slice.mdx +++ b/content/docs/stacks/clarity/functions/slice.mdx @@ -3,7 +3,7 @@ title: slice? description: Extracting a sub-sequence from a sequence in Clarity smart contracts. --- -## Function Signature +## Function signature ```clarity (slice? sequence left-position right-position) @@ -30,14 +30,14 @@ Use `slice?` when you need to: - Validate indices for slicing to ensure data integrity. - Handle sub-sequence extraction operations. -## Best Practices +## Best practices - Ensure the `left-position` and `right-position` are within the bounds of the sequence. - Use meaningful variable names for better readability. - Combine with other sequence functions for comprehensive sequence management. - Handle the possible error cases to ensure robust contract behavior. -## Practical Example: Extracting a Sub-sequence from a String +## Practical example: Extract a sub-sequence from a string Let's implement a function that extracts a sub-sequence from a string: @@ -57,14 +57,14 @@ This example demonstrates: 2. Implementing a public function to handle the sub-sequence extraction. 3. Handling both successful and error cases. -## Common Pitfalls +## Common pitfalls 1. Using `slice?` with indices that are out of bounds, causing the operation to fail. 2. Assuming the sub-sequence will always be valid, leading to unhandled error cases. 3. Not handling all possible conditions, resulting in incomplete sequence management. 4. Overlooking the need for proper error handling and validation. -## Related Functions +## Related functions - `len`: Returns the length of a sequence. - `concat`: Concatenates two sequences. diff --git a/content/docs/stacks/clarity/functions/some.mdx b/content/docs/stacks/clarity/functions/some.mdx index 931372c4..05c3a2e8 100644 --- a/content/docs/stacks/clarity/functions/some.mdx +++ b/content/docs/stacks/clarity/functions/some.mdx @@ -3,7 +3,7 @@ title: some description: Constructing an optional type from a value in Clarity smart contracts. --- -## Function Signature +## Function signature ```clarity (some value) @@ -30,14 +30,14 @@ Use `some` when you need to: - Explicitly handle optional values to ensure data integrity. - Work with optional types in your smart contract. -## Best Practices +## Best practices - Ensure the value passed to `some` is the intended value to be wrapped in an optional type. - Use meaningful variable names for better readability. - Combine with other optional functions for comprehensive optional type management. - Handle the possible error cases to ensure robust contract behavior. -## Practical Example: Constructing an Optional Type +## Practical example: Construct an optional type Let's implement a function that constructs an optional type from a given integer: @@ -56,14 +56,14 @@ This example demonstrates: 2. Implementing a public function to handle the optional type construction. 3. Handling both positive and negative input values. -## Common Pitfalls +## Common pitfalls 1. Using `some` without ensuring the value is the intended value to be wrapped, causing unexpected behavior. 2. Assuming the optional type will always be valid, leading to unhandled error cases. 3. Not handling all possible conditions, resulting in incomplete optional type management. 4. Overlooking the need for proper error handling and validation. -## Related Functions +## Related functions - `is-some`: Checks if an optional type contains a value. - `is-none`: Checks if an optional type is empty. diff --git a/content/docs/stacks/clarity/functions/sqrti.mdx b/content/docs/stacks/clarity/functions/sqrti.mdx index f446ad6e..d37c61d3 100644 --- a/content/docs/stacks/clarity/functions/sqrti.mdx +++ b/content/docs/stacks/clarity/functions/sqrti.mdx @@ -3,7 +3,7 @@ title: sqrti description: Calculating the integer square root of a number in Clarity smart contracts. --- -## Function Signature +## Function signature ```clarity (sqrti n) @@ -30,14 +30,14 @@ Use `sqrti` when you need to: - Ensure precise integer square root calculations. - Handle square root operations. -## Best Practices +## Best practices - Ensure the input value is non-negative to avoid runtime errors. - Use meaningful variable names for better readability. - Combine with other mathematical functions for comprehensive calculations. - Handle the possible error cases to ensure robust contract behavior. -## Practical Example: Calculating Integer Square Roots +## Practical example: Calculate integer square roots Let's implement a function that calculates the integer square root of a given number: @@ -58,14 +58,14 @@ This example demonstrates: 2. Implementing a public function to handle the square root calculation. 3. Handling both small and large input values. -## Common Pitfalls +## Common pitfalls 1. Using `sqrti` with negative numbers, causing the operation to fail. 2. Assuming the result will always be valid, leading to unhandled error cases. 3. Not handling all possible conditions, resulting in incomplete mathematical operations. 4. Overlooking the need for proper error handling and validation. -## Related Functions +## Related functions - `*`: Multiplies two or more numbers. - `+`: Adds two or more numbers. diff --git a/content/docs/stacks/clarity/functions/string-to-int.mdx b/content/docs/stacks/clarity/functions/string-to-int.mdx index a495693e..711781ab 100644 --- a/content/docs/stacks/clarity/functions/string-to-int.mdx +++ b/content/docs/stacks/clarity/functions/string-to-int.mdx @@ -3,7 +3,7 @@ title: string-to-int? description: Converting a string to an optional integer in Clarity smart contracts. --- -## Function Signature +## Function signature ```clarity (string-to-int? string) @@ -30,14 +30,14 @@ Use `string-to-int?` when you need to: - Validate string-to-integer conversions to ensure data integrity. - Handle numeric conversions in your smart contract. -## Best Practices +## Best practices - Ensure the input string is correctly formatted and represents a valid integer. - Use meaningful variable names for better readability. - Combine with other string and numeric functions for comprehensive data management. - Handle the possible error cases to ensure robust contract behavior. -## Practical Example: Converting a String to an Integer +## Practical example: Convert a string to an integer Let's implement a function that converts a string to an optional integer: @@ -57,14 +57,14 @@ This example demonstrates: 2. Implementing a public function to handle the string-to-integer conversion. 3. Handling both valid and invalid string inputs. -## Common Pitfalls +## Common pitfalls 1. Using `string-to-int?` with incorrectly formatted or invalid string inputs, causing the operation to return `none`. 2. Assuming the conversion will always succeed, leading to unhandled error cases. 3. Not handling all possible conditions, resulting in incomplete data management. 4. Overlooking the need for proper error handling and validation. -## Related Functions +## Related functions - `string-to-uint?`: Converts a string to an optional unsigned integer. - `int-to-ascii`: Converts an integer to a string-ascii representation. diff --git a/content/docs/stacks/clarity/functions/string-to-uint.mdx b/content/docs/stacks/clarity/functions/string-to-uint.mdx index fd7e0f5b..cc45b6de 100644 --- a/content/docs/stacks/clarity/functions/string-to-uint.mdx +++ b/content/docs/stacks/clarity/functions/string-to-uint.mdx @@ -3,7 +3,7 @@ title: string-to-uint? description: Converting a string to an optional unsigned integer in Clarity smart contracts. --- -## Function Signature +## Function signature ```clarity (string-to-uint? string) @@ -30,14 +30,14 @@ Use `string-to-uint?` when you need to: - Validate string-to-unsigned-integer conversions to ensure data integrity. - Handle numeric conversions in your smart contract. -## Best Practices +## Best practices - Ensure the input string is correctly formatted and represents a valid unsigned integer. - Use meaningful variable names for better readability. - Combine with other string and numeric functions for comprehensive data management. - Handle the possible error cases to ensure robust contract behavior. -## Practical Example: Converting a String to an Unsigned Integer +## Practical example: Convert a string to an unsigned integer Let's implement a function that converts a string to an optional unsigned integer: @@ -57,14 +57,14 @@ This example demonstrates: 2. Implementing a public function to handle the string-to-unsigned-integer conversion. 3. Handling both valid and invalid string inputs. -## Common Pitfalls +## Common pitfalls 1. Using `string-to-uint?` with incorrectly formatted or invalid string inputs, causing the operation to return `none`. 2. Assuming the conversion will always succeed, leading to unhandled error cases. 3. Not handling all possible conditions, resulting in incomplete data management. 4. Overlooking the need for proper error handling and validation. -## Related Functions +## Related functions - `string-to-int?`: Converts a string to an optional signed integer. - `int-to-ascii`: Converts an integer to a string-ascii representation. diff --git a/content/docs/stacks/clarity/functions/stx-account.mdx b/content/docs/stacks/clarity/functions/stx-account.mdx index dd2f4e57..a2c58c5d 100644 --- a/content/docs/stacks/clarity/functions/stx-account.mdx +++ b/content/docs/stacks/clarity/functions/stx-account.mdx @@ -3,7 +3,7 @@ title: stx-account description: Querying STX account information in Clarity smart contracts. --- -## Function Signature +## Function signature ```clarity (stx-account principal) @@ -30,14 +30,14 @@ Use `stx-account` when you need to: - Ensure accurate account details for data integrity. - Handle account-related operations in your smart contract. -## Best Practices +## Best practices - Ensure the `principal` is correctly formatted and valid. - Use meaningful variable names for better readability. - Combine with other account functions for comprehensive account management. - Handle the possible error cases to ensure robust contract behavior. -## Practical Example: Querying STX Account Information +## Practical example: Query STX account information Let's implement a function that queries the STX account information for a given principal: @@ -56,14 +56,14 @@ This example demonstrates: 2. Implementing a public function to handle the account information query. 3. Handling both successful and error cases. -## Common Pitfalls +## Common pitfalls 1. Using `stx-account` with an incorrectly formatted or invalid `principal`, causing the operation to fail. 2. Assuming the account information will always be valid, leading to unhandled error cases. 3. Not handling all possible conditions, resulting in incomplete account management. 4. Overlooking the need for proper error handling and validation. -## Related Functions +## Related functions - `stx-get-balance`: Queries the STX balance of a principal. - `stx-transfer?`: Transfers STX from one principal to another. diff --git a/content/docs/stacks/clarity/functions/stx-burn.mdx b/content/docs/stacks/clarity/functions/stx-burn.mdx index 596b6115..3491032c 100644 --- a/content/docs/stacks/clarity/functions/stx-burn.mdx +++ b/content/docs/stacks/clarity/functions/stx-burn.mdx @@ -3,7 +3,7 @@ title: stx-burn? description: Burning STX from a principal's account in Clarity smart contracts. --- -## Function Signature +## Function signature ```clarity (stx-burn? amount sender) @@ -30,14 +30,14 @@ Use `stx-burn?` when you need to: - Validate the burn operation to ensure data integrity. - Handle STX burning operations in your smart contract. -## Best Practices +## Best practices - Ensure the `amount` is positive and the `sender` has sufficient balance. - Use meaningful variable names for better readability. - Combine with other STX functions for comprehensive account management. - Handle the possible error cases to ensure robust contract behavior. -## Practical Example: Burning STX from an Account +## Practical example: Burn STX from an account Let's implement a function that burns a specified amount of STX from the `tx-sender`: @@ -55,14 +55,14 @@ This example demonstrates: 2. Implementing a public function to handle the STX burning operation. 3. Handling both successful and error cases. -## Common Pitfalls +## Common pitfalls 1. Using `stx-burn?` with a non-positive amount, causing the operation to fail. 2. Assuming the burn operation will always succeed, leading to unhandled error cases. 3. Not handling all possible conditions, resulting in incomplete account management. 4. Overlooking the need for proper error handling and validation. -## Related Functions +## Related functions - `stx-get-balance`: Queries the STX balance of a principal. - `stx-transfer?`: Transfers STX from one principal to another. diff --git a/content/docs/stacks/clarity/functions/stx-get-balance.mdx b/content/docs/stacks/clarity/functions/stx-get-balance.mdx index 49eb6120..fd8b63d1 100644 --- a/content/docs/stacks/clarity/functions/stx-get-balance.mdx +++ b/content/docs/stacks/clarity/functions/stx-get-balance.mdx @@ -3,7 +3,7 @@ title: stx-get-balance description: Querying the STX balance of a principal in Clarity smart contracts. --- -## Function Signature +## Function signature ```clarity (stx-get-balance owner) @@ -30,14 +30,14 @@ Use `stx-get-balance` when you need to: - Ensure accurate balance information for data integrity. - Handle balance-related operations in your smart contract. -## Best Practices +## Best practices - Ensure the `principal` is correctly formatted and valid. - Use meaningful variable names for better readability. - Combine with other account functions for comprehensive account management. - Handle the possible error cases to ensure robust contract behavior. -## Practical Example: Querying STX Balance +## Practical example: Query STX balance Let's implement a function that queries the STX balance of a given principal: @@ -58,14 +58,14 @@ This example demonstrates: 2. Implementing a public function to handle the balance query. 3. Handling both successful and error cases. -## Common Pitfalls +## Common pitfalls 1. Using `stx-get-balance` with an incorrectly formatted or invalid `principal`, causing the operation to fail. 2. Assuming the balance query will always succeed, leading to unhandled error cases. 3. Not handling all possible conditions, resulting in incomplete account management. 4. Overlooking the need for proper error handling and validation. -## Related Functions +## Related functions - `stx-transfer?`: Transfers STX from one principal to another. - `stx-burn?`: Burns STX from a principal's account. diff --git a/content/docs/stacks/clarity/functions/stx-transfer-memo.mdx b/content/docs/stacks/clarity/functions/stx-transfer-memo.mdx index 08dc28c2..f6043be8 100644 --- a/content/docs/stacks/clarity/functions/stx-transfer-memo.mdx +++ b/content/docs/stacks/clarity/functions/stx-transfer-memo.mdx @@ -3,7 +3,7 @@ title: stx-transfer-memo? description: Transferring STX with a memo field in Clarity smart contracts. --- -## Function Signature +## Function signature ```clarity (stx-transfer-memo? amount sender recipient memo) @@ -30,14 +30,14 @@ Use `stx-transfer-memo?` when you need to: - Validate the transfer operation to ensure data integrity. - Handle STX transfers with memos in your smart contract. -## Best Practices +## Best practices - Ensure the `amount` is positive and the `sender` has sufficient balance. - Use meaningful variable names for better readability. - Combine with other STX functions for comprehensive account management. - Handle the possible error cases to ensure robust contract behavior. -## Practical Example: Transferring STX with a Memo +## Practical example: Transfer STX with a memo Let's implement a function that transfers STX with a memo from the `tx-sender` to a recipient: @@ -58,14 +58,14 @@ This example demonstrates: 2. Implementing a public function to handle the STX transfer with a memo. 3. Handling both successful and error cases. -## Common Pitfalls +## Common pitfalls 1. Using `stx-transfer-memo?` with a non-positive amount, causing the operation to fail. 2. Assuming the transfer operation will always succeed, leading to unhandled error cases. 3. Not handling all possible conditions, resulting in incomplete account management. 4. Overlooking the need for proper error handling and validation. -## Related Functions +## Related functions - `stx-get-balance`: Queries the STX balance of a principal. - `stx-transfer?`: Transfers STX from one principal to another without a memo. diff --git a/content/docs/stacks/clarity/functions/stx-transfer.mdx b/content/docs/stacks/clarity/functions/stx-transfer.mdx index c29f76e6..846cc98a 100644 --- a/content/docs/stacks/clarity/functions/stx-transfer.mdx +++ b/content/docs/stacks/clarity/functions/stx-transfer.mdx @@ -3,7 +3,7 @@ title: stx-transfer? description: Transferring STX between principals in Clarity smart contracts. --- -## Function Signature +## Function signature ```clarity (stx-transfer? amount sender recipient) @@ -30,14 +30,14 @@ Use `stx-transfer?` when you need to: - Validate the transfer operation to ensure data integrity. - Handle STX transfers in your smart contract. -## Best Practices +## Best practices - Ensure the `amount` is positive and the `sender` has sufficient balance. - Use meaningful variable names for better readability. - Combine with other STX functions for comprehensive account management. - Handle the possible error cases to ensure robust contract behavior. -## Practical Example: Transferring STX +## Practical example: Transfer STX Let's implement a function that transfers STX from the `tx-sender` to a recipient: @@ -58,14 +58,14 @@ This example demonstrates: 2. Implementing a public function to handle the STX transfer. 3. Handling both successful and error cases. -## Common Pitfalls +## Common pitfalls 1. Using `stx-transfer?` with a non-positive amount, causing the operation to fail. 2. Assuming the transfer operation will always succeed, leading to unhandled error cases. 3. Not handling all possible conditions, resulting in incomplete account management. 4. Overlooking the need for proper error handling and validation. -## Related Functions +## Related functions - `stx-get-balance`: Queries the STX balance of a principal. - `stx-transfer-memo?`: Transfers STX from one principal to another with a memo. diff --git a/content/docs/stacks/clarity/functions/subtract.mdx b/content/docs/stacks/clarity/functions/subtract.mdx index 932284d0..aaea8f5b 100644 --- a/content/docs/stacks/clarity/functions/subtract.mdx +++ b/content/docs/stacks/clarity/functions/subtract.mdx @@ -5,7 +5,7 @@ description: Using the subtraction function for arithmetic operations in Clarity The subtraction function (`-`) in Clarity performs subtraction on a variable number of integer inputs. It's a fundamental arithmetic operation used in many smart contract calculations. -## Function Signature +## Function signature ```clarity (- i1 i2...) @@ -32,14 +32,14 @@ Use the subtraction function when you need to: - Calculate the difference between two or more values. - Implement mathematical formulas that involve subtraction. -## Best Practices +## Best practices - Always consider the possibility of underflow when subtracting from small numbers. - Use appropriate types (int or uint) based on your needs and expected value ranges. - Be aware that subtracting a negative number results in addition. - Consider using checked arithmetic functions if underflow detection is critical. -## Practical Example: Simple Escrow Contract +## Practical example: Simple escrow contract Let's implement a basic escrow contract that uses subtraction to manage balances: @@ -95,13 +95,13 @@ This example demonstrates: 2. Using subtraction to update the escrow balance when completing a transfer. 3. Combining subtraction with addition to handle fees and balance updates. -## Common Pitfalls +## Common pitfalls 1. Overlooking potential underflow when subtracting from small numbers. 2. Not considering the effect of subtracting negative numbers (for int types). 3. Forgetting to update related variables or state when decrementing values. -## Related Functions +## Related functions - `+`: Used for addition operations. - `*`: Used for multiplication operations. diff --git a/content/docs/stacks/clarity/functions/to-consensus-buff.mdx b/content/docs/stacks/clarity/functions/to-consensus-buff.mdx index 15dbaf46..17c76fbe 100644 --- a/content/docs/stacks/clarity/functions/to-consensus-buff.mdx +++ b/content/docs/stacks/clarity/functions/to-consensus-buff.mdx @@ -3,7 +3,7 @@ title: to-consensus-buff? description: Serializing a Clarity value into a buffer for consensus in Clarity smart contracts. --- -## Function Signature +## Function signature ```clarity (to-consensus-buff? value) @@ -30,14 +30,14 @@ Use `to-consensus-buff?` when you need to: - Validate the serialization process to ensure data integrity. - Handle value serialization in your smart contract. -## Best Practices +## Best practices - Ensure the input value is correctly formatted and valid. - Use meaningful variable names for better readability. - Combine with other serialization functions for comprehensive data management. - Handle the possible error cases to ensure robust contract behavior. -## Practical Example: Serializing a Clarity Value +## Practical example: Serialize a Clarity value Let's implement a function that serializes an integer value into a buffer: @@ -61,14 +61,14 @@ This example demonstrates: 2. Implementing a public function to handle the serialization process. 3. Handling both successful and error cases. -## Common Pitfalls +## Common pitfalls 1. Using `to-consensus-buff?` with incorrectly formatted or invalid input values, causing the operation to fail. 2. Assuming the serialization will always succeed, leading to unhandled error cases. 3. Not handling all possible conditions, resulting in incomplete data management. 4. Overlooking the need for proper error handling and validation. -## Related Functions +## Related functions - `from-consensus-buff?`: Deserializes a buffer into a Clarity value. - `buff-to-int-be`: Converts a big-endian buffer to an integer. diff --git a/content/docs/stacks/clarity/functions/to-int.mdx b/content/docs/stacks/clarity/functions/to-int.mdx index 0c496fe0..570305c4 100644 --- a/content/docs/stacks/clarity/functions/to-int.mdx +++ b/content/docs/stacks/clarity/functions/to-int.mdx @@ -3,7 +3,7 @@ title: to-int description: Converting an unsigned integer to a signed integer in Clarity smart contracts. --- -## Function Signature +## Function signature ```clarity (to-int value) @@ -30,14 +30,14 @@ Use `to-int` when you need to: - Validate the conversion process to ensure data integrity. - Handle integer conversions in your smart contract. -## Best Practices +## Best practices - Ensure the input value is within the range that can be represented as a signed integer. - Use meaningful variable names for better readability. - Combine with other integer functions for comprehensive data management. - Handle the possible error cases to ensure robust contract behavior. -## Practical Example: Converting Unsigned Integer to Signed Integer +## Practical example: Convert unsigned integer to signed integer Let's implement a function that converts an unsigned integer to a signed integer: @@ -57,14 +57,14 @@ This example demonstrates: 2. Implementing a public function to handle the conversion process. 3. Handling both small and large input values. -## Common Pitfalls +## Common pitfalls 1. Using `to-int` with values that exceed the range of signed integers, causing unexpected behavior. 2. Assuming the conversion will always succeed, leading to unhandled error cases. 3. Not handling all possible conditions, resulting in incomplete data management. 4. Overlooking the need for proper error handling and validation. -## Related Functions +## Related functions - `to-uint`: Converts a signed integer to an unsigned integer. - `int-to-ascii`: Converts an integer to a string-ascii representation. diff --git a/content/docs/stacks/clarity/functions/to-uint.mdx b/content/docs/stacks/clarity/functions/to-uint.mdx index 085e936b..90f070e3 100644 --- a/content/docs/stacks/clarity/functions/to-uint.mdx +++ b/content/docs/stacks/clarity/functions/to-uint.mdx @@ -3,7 +3,7 @@ title: to-uint description: Converting a signed integer to an unsigned integer in Clarity smart contracts. --- -## Function Signature +## Function signature ```clarity (to-uint value) @@ -30,14 +30,14 @@ Use `to-uint` when you need to: - Validate the conversion process to ensure data integrity. - Handle integer conversions in your smart contract. -## Best Practices +## Best practices - Ensure the input value is non-negative to avoid runtime errors. - Use meaningful variable names for better readability. - Combine with other integer functions for comprehensive data management. - Handle the possible error cases to ensure robust contract behavior. -## Practical Example: Converting Signed Integer to Unsigned Integer +## Practical example: Convert signed integer to unsigned integer Let's implement a function that converts a signed integer to an unsigned integer: @@ -57,14 +57,14 @@ This example demonstrates: 2. Implementing a public function to handle the conversion process. 3. Handling both positive and zero input values. -## Common Pitfalls +## Common pitfalls 1. Using `to-uint` with negative values, causing a runtime error. 2. Assuming the conversion will always succeed, leading to unhandled error cases. 3. Not handling all possible conditions, resulting in incomplete data management. 4. Overlooking the need for proper error handling and validation. -## Related Functions +## Related functions - `to-int`: Converts an unsigned integer to a signed integer. - `int-to-ascii`: Converts an integer to a string-ascii representation. diff --git a/content/docs/stacks/clarity/functions/try.mdx b/content/docs/stacks/clarity/functions/try.mdx index 146057d1..88d43551 100644 --- a/content/docs/stacks/clarity/functions/try.mdx +++ b/content/docs/stacks/clarity/functions/try.mdx @@ -3,7 +3,7 @@ title: try! description: Handling errors in Clarity smart contracts using the `try!` function. --- -## Function Signature +## Function signature ```clarity (try! expression) @@ -30,14 +30,14 @@ Use `try!` when you need to: - Validate operations and handle errors gracefully. - Handle responses in your smart contract. -## Best Practices +## Best practices - Ensure the expression returns a response type `(response T E)`. - Use meaningful variable names for better readability. - Combine with other error handling functions for comprehensive error management. - Handle the possible error cases to ensure robust contract behavior. -## Practical Example: Handling Errors in a Transfer Function +## Practical example: Handle errors in a transfer function Let's implement a function that transfers STX and handles errors using `try!`: @@ -61,14 +61,14 @@ This example demonstrates: 2. Implementing a public function to handle the transfer and error propagation. 3. Handling both successful and error cases. -## Common Pitfalls +## Common pitfalls 1. Using `try!` with expressions that do not return a response type, causing runtime errors. 2. Assuming the operation will always succeed, leading to unhandled error cases. 3. Not handling all possible conditions, resulting in incomplete error management. 4. Overlooking the need for proper error handling and validation. -## Related Functions +## Related functions - `unwrap!`: Unwraps an optional value, causing a runtime error if the value is `none`. - `asserts!`: Asserts a condition, causing a runtime error if the condition is false. diff --git a/content/docs/stacks/clarity/functions/tuple.mdx b/content/docs/stacks/clarity/functions/tuple.mdx index 90b62d05..77a218be 100644 --- a/content/docs/stacks/clarity/functions/tuple.mdx +++ b/content/docs/stacks/clarity/functions/tuple.mdx @@ -52,14 +52,14 @@ Use `tuple` when you need to: - Ensure data integrity by providing a clear structure for related values. - Handle grouped data in your smart contract. -## Best Practices +## Best practices - Use descriptive names for tuple fields for better readability. - Ensure the types of the tuple fields are appropriate for the data they represent. - Combine with other data types and functions for comprehensive data management. - Handle the possible error cases to ensure robust contract behavior. -## Practical Example: Using Tuples to Store User Information +## Practical example: Use tuples to store user information Let's implement a function that stores and retrieves user information using tuples: @@ -109,14 +109,14 @@ This example demonstrates: 2. Implementing functions to set and get user information using tuples. 3. Handling both successful and error cases. -## Common Pitfalls +## Common pitfalls 1. Using non-descriptive names for tuple fields, causing confusion. 2. Assuming the tuple structure will always be valid, leading to unhandled error cases. 3. Not handling all possible conditions, resulting in incomplete data management. 4. Overlooking the need for proper error handling and validation. -## Related Functions +## Related functions - `map-set`: Sets a value in a map. - `map-get?`: Retrieves a value from a map. diff --git a/content/docs/stacks/clarity/functions/unwrap-err-panic.mdx b/content/docs/stacks/clarity/functions/unwrap-err-panic.mdx index 60b10cc5..aa42a409 100644 --- a/content/docs/stacks/clarity/functions/unwrap-err-panic.mdx +++ b/content/docs/stacks/clarity/functions/unwrap-err-panic.mdx @@ -3,7 +3,7 @@ title: unwrap-err-panic description: Unpacking error responses and throwing runtime errors in Clarity smart contracts. --- -## Function Signature +## Function signature ```clarity (unwrap-err-panic response-input) @@ -30,14 +30,14 @@ Use `unwrap-err-panic` when you need to: - Validate the error unpacking process to ensure data integrity. - Handle error responses in your smart contract and throw runtime errors when necessary. -## Best Practices +## Best practices - Ensure the input value is a response type. - Use meaningful variable names for better readability. - Combine with other error handling functions for comprehensive error management. - Handle the possible error cases to ensure robust contract behavior. -## Practical Example: Unpacking an Error Response and Throwing a Runtime Error +## Practical example: Unpack an error response and throwing a runtime error Let's implement a function that processes an error response using `unwrap-err-panic`: @@ -61,14 +61,14 @@ This example demonstrates: 2. Implementing a public function to handle the error unpacking process. 3. Handling both successful and error cases, with runtime errors thrown for `ok` values. -## Common Pitfalls +## Common pitfalls 1. Using `unwrap-err-panic` with values that are not response types, causing runtime errors. 2. Assuming the error unpacking will always succeed, leading to unhandled error cases. 3. Not handling all possible conditions, resulting in incomplete error management. 4. Overlooking the need for proper error handling and validation. -## Related Functions +## Related functions - `unwrap!`: Unpacks optional and response types, returning a thrown value if unpacking fails. - `unwrap-err!`: Unpacks error responses, returning a thrown value if the response is `ok`. diff --git a/content/docs/stacks/clarity/functions/unwrap-err.mdx b/content/docs/stacks/clarity/functions/unwrap-err.mdx index 4f68daba..515d4b6d 100644 --- a/content/docs/stacks/clarity/functions/unwrap-err.mdx +++ b/content/docs/stacks/clarity/functions/unwrap-err.mdx @@ -3,7 +3,7 @@ title: unwrap-err! description: Unpacking error responses in Clarity smart contracts. --- -## Function Signature +## Function signature ```clarity (unwrap-err! response-input thrown-value) @@ -30,14 +30,14 @@ Use `unwrap-err!` when you need to: - Validate the error unpacking process to ensure data integrity. - Handle error responses in your smart contract. -## Best Practices +## Best practices - Ensure the input value is a response type. - Use meaningful variable names for better readability. - Combine with other error handling functions for comprehensive error management. - Handle the possible error cases to ensure robust contract behavior. -## Practical Example: Unpacking an Error Response +## Practical example: Unpack an error response Let's implement a function that processes an error response using `unwrap-err!`: @@ -61,14 +61,14 @@ This example demonstrates: 2. Implementing a public function to handle the error unpacking process. 3. Handling both successful and error cases. -## Common Pitfalls +## Common pitfalls 1. Using `unwrap-err!` with values that are not response types, causing runtime errors. 2. Assuming the error unpacking will always succeed, leading to unhandled error cases. 3. Not handling all possible conditions, resulting in incomplete error management. 4. Overlooking the need for proper error handling and validation. -## Related Functions +## Related functions - `unwrap!`: Unpacks optional and response types, returning a thrown value if unpacking fails. - `unwrap-panic`: Unpacks optional and response types, throwing a runtime error if unpacking fails. diff --git a/content/docs/stacks/clarity/functions/unwrap-panic.mdx b/content/docs/stacks/clarity/functions/unwrap-panic.mdx index bccff480..78c39cad 100644 --- a/content/docs/stacks/clarity/functions/unwrap-panic.mdx +++ b/content/docs/stacks/clarity/functions/unwrap-panic.mdx @@ -3,7 +3,7 @@ title: unwrap-panic description: Unpacking optional and response types and throwing runtime errors in Clarity smart contracts. --- -## Function Signature +## Function signature ```clarity (unwrap-panic option-input) @@ -45,14 +45,14 @@ Use `unwrap-panic` when you need to: - Validate the unpacking process to ensure data integrity. - Handle optional and response types in your smart contract and throw runtime errors when necessary. -## Best Practices +## Best practices - Ensure the input value is an optional or response type. - Use meaningful variable names for better readability. - Combine with other error handling functions for comprehensive error management. - Handle the possible error cases to ensure robust contract behavior. -## Practical Example: Unpacking an Optional Value and Throwing a Runtime Error +## Practical example: Unpack an optional value and throwing a runtime error Let's implement a function that retrieves a value from a map and unpacks it using `unwrap-panic`: @@ -74,14 +74,14 @@ Let's implement a function that retrieves a value from a map and unpacks it usin (get-user-age 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR) ;; Throws a runtime exception ``` -## Common Pitfalls +## Common pitfalls 1. Using `unwrap-panic` with values that are not optional or response types, causing runtime errors. 2. Assuming the unpacking will always succeed, leading to unhandled error cases. 3. Not handling all possible conditions, resulting in incomplete error management. 4. Overlooking the need for proper error handling and validation. -## Related Functions +## Related functions - `unwrap!`: Unpacks optional and response types, returning a thrown value if unpacking fails. - `unwrap-err!`: Unpacks error responses, returning a thrown value if the response is `ok`. diff --git a/content/docs/stacks/clarity/functions/unwrap.mdx b/content/docs/stacks/clarity/functions/unwrap.mdx index 5a5c36bf..29032dd5 100644 --- a/content/docs/stacks/clarity/functions/unwrap.mdx +++ b/content/docs/stacks/clarity/functions/unwrap.mdx @@ -3,7 +3,7 @@ title: unwrap! description: Unpacking optional and response types in Clarity smart contracts. --- -## Function Signature +## Function signature ```clarity (unwrap! option-input thrown-value) @@ -53,14 +53,14 @@ Use `unwrap!` when you need to: - Validate the unpacking process to ensure data integrity. - Handle optional and response types in your smart contract. -## Best Practices +## Best practices - Ensure the input value is an optional or response type. - Use meaningful variable names for better readability. - Combine with other error handling functions for comprehensive error management. - Handle the possible error cases to ensure robust contract behavior. -## Practical Example: Unpacking an Optional Value +## Practical example: Unpack an optional value Let's implement a function that retrieves a value from a map and unpacks it using `unwrap!`: @@ -110,14 +110,14 @@ This example demonstrates: 2. Implementing a public function to handle the unpacking process. 3. Handling both successful and error cases. -## Common Pitfalls +## Common pitfalls 1. Using `unwrap!` with values that are not optional or response types, causing runtime errors. 2. Assuming the unpacking will always succeed, leading to unhandled error cases. 3. Not handling all possible conditions, resulting in incomplete error management. 4. Overlooking the need for proper error handling and validation. -## Related Functions +## Related functions - `try!`: Unpacks optional and response types, returning `none` or the `err` value if unpacking fails. - `unwrap-panic`: Unpacks optional and response types, throwing a runtime error if unpacking fails. diff --git a/content/docs/stacks/clarity/functions/use-trait.mdx b/content/docs/stacks/clarity/functions/use-trait.mdx index 8e2b4259..03f9e582 100644 --- a/content/docs/stacks/clarity/functions/use-trait.mdx +++ b/content/docs/stacks/clarity/functions/use-trait.mdx @@ -3,7 +3,7 @@ title: use-trait description: Importing and using traits from other contracts in Clarity smart contracts. --- -## Function Signature +## Function signature ```clarity (use-trait trait-alias trait-identifier) @@ -30,14 +30,14 @@ Use `use-trait` when you need to: - Ensure code reusability and modularity by leveraging traits. - Handle trait imports in your smart contract. -## Best Practices +## Best practices - Use descriptive names for trait aliases for better readability. - Ensure the trait identifier is correctly formatted and valid. - Combine with other contract functions for comprehensive contract management. - Handle the possible error cases to ensure robust contract behavior. -## Practical Example: Importing and Using a Trait +## Practical example: Import and use a trait Let's implement a function that imports a trait and uses it in a contract: @@ -58,14 +58,14 @@ This example demonstrates: 2. Implementing a public function to use the imported trait. 3. Handling both successful and error cases. -## Common Pitfalls +## Common pitfalls 1. Using `use-trait` with incorrectly formatted or invalid trait identifiers, causing runtime errors. 2. Assuming the trait import will always succeed, leading to unhandled error cases. 3. Not handling all possible conditions, resulting in incomplete contract management. 4. Overlooking the need for proper error handling and validation. -## Related Functions +## Related functions - `contract-of`: Returns the principal of the contract implementing the trait. - `define-trait`: Defines a new trait in the current contract. diff --git a/content/docs/stacks/clarity/functions/var-get.mdx b/content/docs/stacks/clarity/functions/var-get.mdx index dd62fee9..410eab96 100644 --- a/content/docs/stacks/clarity/functions/var-get.mdx +++ b/content/docs/stacks/clarity/functions/var-get.mdx @@ -3,7 +3,7 @@ title: var-get description: Retrieving the value of a data variable in Clarity smart contracts. --- -## Function Signature +## Function signature ```clarity (var-get var-name) @@ -30,14 +30,14 @@ Use `var-get` when you need to: - Validate the retrieval process to ensure data integrity. - Handle data variables in your smart contract. -## Best Practices +## Best practices - Ensure the variable name is correctly formatted and valid. - Use meaningful variable names for better readability. - Combine with other data functions for comprehensive data management. - Handle the possible error cases to ensure robust contract behavior. -## Practical Example: Retrieving a Data Variable +## Practical example: Retrieve a data variable ```clarity (define-data-var cursor int 6) @@ -55,14 +55,14 @@ This example demonstrates: 2. Implementing a public function to handle the retrieval process. 3. Handling both successful and error cases. -## Common Pitfalls +## Common pitfalls 1. Using `var-get` with incorrectly formatted or invalid variable names, causing runtime errors. 2. Assuming the retrieval will always succeed, leading to unhandled error cases. 3. Not handling all possible conditions, resulting in incomplete data management. 4. Overlooking the need for proper error handling and validation. -## Related Functions +## Related functions - `var-set`: Sets the value of a data variable. - `map-get?`: Retrieves a value from a map. diff --git a/content/docs/stacks/clarity/functions/var-set.mdx b/content/docs/stacks/clarity/functions/var-set.mdx index aab4ce9d..605466b4 100644 --- a/content/docs/stacks/clarity/functions/var-set.mdx +++ b/content/docs/stacks/clarity/functions/var-set.mdx @@ -3,7 +3,7 @@ title: var-set description: Setting the value of a data variable in Clarity smart contracts. --- -## Function Signature +## Function signature ```clarity (var-set var-name expr1) @@ -30,14 +30,14 @@ Use `var-set` when you need to: - Validate the update process to ensure data integrity. - Handle data variables in your smart contract. -## Best Practices +## Best practices - Ensure the variable name is correctly formatted and valid. - Use meaningful variable names for better readability. - Combine with other data functions for comprehensive data management. - Handle the possible error cases to ensure robust contract behavior. -## Practical Example: Setting a Data Variable +## Practical example: Set a data variable Let's implement a function that sets the value of a data variable: @@ -58,14 +58,14 @@ This example demonstrates: 2. Implementing a public function to handle the update process. 3. Handling both successful and error cases. -## Common Pitfalls +## Common pitfalls 1. Using `var-set` with incorrectly formatted or invalid variable names, causing runtime errors. 2. Assuming the update will always succeed, leading to unhandled error cases. 3. Not handling all possible conditions, resulting in incomplete data management. 4. Overlooking the need for proper error handling and validation. -## Related Functions +## Related functions - `var-get`: Retrieves the value of a data variable. - `map-set`: Sets a value in a map. diff --git a/content/docs/stacks/clarity/functions/xor.mdx b/content/docs/stacks/clarity/functions/xor.mdx index 50657db1..2e3dac7f 100644 --- a/content/docs/stacks/clarity/functions/xor.mdx +++ b/content/docs/stacks/clarity/functions/xor.mdx @@ -3,7 +3,7 @@ title: xor description: Performing a bitwise exclusive OR operation in Clarity smart contracts. --- -## Function Signature +## Function signature ```clarity (xor int1 int2) @@ -30,14 +30,14 @@ Use `xor` when you need to: - Toggle between two states based on certain conditions. - Enhance the security of your smart contract through cryptographic operations. -## Best Practices +## Best practices - Ensure the integers used with `xor` are within the valid range for your application. - Use meaningful variable names to enhance code readability. - Combine `xor` with other logical operations to implement complex conditions. - Handle possible edge cases to ensure robust contract behavior. -## Practical Example: Simple Encryption +## Practical example: Simple encryption Let's implement a simple encryption and decryption mechanism using the `xor` function: @@ -60,14 +60,14 @@ This example demonstrates: 2. Implementing public functions to handle encryption and decryption. 3. Handling both successful and error cases. -## Common Pitfalls +## Common pitfalls 1. Using `xor` with non-integer types, causing runtime errors. 2. Misunderstanding the behavior of `xor`, leading to incorrect logic implementation. 3. Not considering edge cases, resulting in incomplete data management. 4. Overlooking the need for proper error handling and validation. -## Related Functions +## Related functions - `and`: Performs a bitwise AND operation. - `or`: Performs a bitwise OR operation. diff --git a/content/docs/stacks/clarity/handling-optionals-and-errors.mdx b/content/docs/stacks/clarity/handling-optionals-and-errors.mdx index 64255955..c3d0cb53 100644 --- a/content/docs/stacks/clarity/handling-optionals-and-errors.mdx +++ b/content/docs/stacks/clarity/handling-optionals-and-errors.mdx @@ -100,7 +100,7 @@ Clarity's optional value and error handling functions are designed with several ) ``` -## Practical example: safe token transfer system +## Practical example: Safe token transfer system Let's implement a simple token system that demonstrates the use of optional values and error handling: diff --git a/content/docs/stacks/clarity/optimizations.mdx b/content/docs/stacks/clarity/optimizations.mdx index d9faf7ef..60287ad8 100644 --- a/content/docs/stacks/clarity/optimizations.mdx +++ b/content/docs/stacks/clarity/optimizations.mdx @@ -27,7 +27,7 @@ Clarity's map functions are designed with blockchain-specific considerations in (define-map map-name {key-type} {value-type}) ``` -**Best Practices**: +**Best practices**: - Choose appropriate key and value types to represent your data efficiently. - Consider using composite keys (tuples) for more complex data relationships. @@ -47,7 +47,7 @@ Clarity's map functions are designed with blockchain-specific considerations in (map-set map-name key value) ``` -**Best Practices**: +**Best practices**: - Always check if the key exists before updating to avoid unintended overwrites. - Use in conjunction with appropriate access controls. @@ -70,7 +70,7 @@ Clarity's map functions are designed with blockchain-specific considerations in (map-get? map-name key) ``` -**Best Practices**: +**Best practices**: - Always handle the case where the key might not exist (returns none). - Use `unwrap!` or `unwrap-panic` when you're certain the key exists. @@ -91,7 +91,7 @@ Clarity's map functions are designed with blockchain-specific considerations in (map-delete map-name key) ``` -**Best Practices**: +**Best practices**: - Be cautious when deleting data, as it can't be recovered once deleted. - Consider using a "soft delete" approach for data that might need to be referenced later. @@ -104,7 +104,7 @@ Clarity's map functions are designed with blockchain-specific considerations in (ok (map-delete user-balances user)))) ``` -## Practical Example: Simple Voting System +## Practical example: Simple voting system Let's implement a basic voting system using map functions to demonstrate their practical use: diff --git a/content/docs/stacks/clarity/time-and-blocks.mdx b/content/docs/stacks/clarity/time-and-blocks.mdx index a6648e39..9a114735 100644 --- a/content/docs/stacks/clarity/time-and-blocks.mdx +++ b/content/docs/stacks/clarity/time-and-blocks.mdx @@ -26,7 +26,7 @@ Clarity's block info functions are designed with blockchain-specific considerati (block-height) ``` -**Best Practices**: +**Best practices**: - Use for long-term time measurements (hours/days) rather than short intervals. - Consider potential variations in block time when planning time-sensitive operations. @@ -50,7 +50,7 @@ Clarity's block info functions are designed with blockchain-specific considerati (burn-block-height) ``` -**Best Practices**: +**Best practices**: - Prefer this over `block-height` for more accurate time estimations. - Remember that Bitcoin block times can still vary, so allow for some flexibility. @@ -75,7 +75,7 @@ Clarity's block info functions are designed with blockchain-specific considerati (get-block-info? property-name block-height-int) ``` -**Best Practices**: +**Best practices**: - Cache retrieved information when possible to save processing costs. - Be aware of the limit on how far back you can query block information. @@ -90,7 +90,7 @@ Clarity's block info functions are designed with blockchain-specific considerati (err u3)))) ``` -### Practical Example: Token Balance Snapshot for Voting +### Practical example: Token balance snapshot for voting Let's implement a simple voting system where voting power is determined by a user's token balance at a specific "snapshot" block height. This example combines the use of `at-block` and `get-block-info?` functions to create a time-based voting mechanism.