clarity function updates

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.
 

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:
 

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:
 

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.
 

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.

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.

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,15 +30,15 @@ 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.
 - Consider using `concat` for joining two lists instead of repeatedly using `append`.
 - 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.

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`).

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.

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.

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.