multiply

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

(* i1 i2...)

• Input: Two or more integers (int or uint)
• Output: A single integer (int or uint)

Why it matters

The multiplication function is crucial for:

1. Performing basic arithmetic calculations within smart contracts.
2. Scaling values, such as calculating fees or interest.
3. Implementing more complex mathematical operations.
4. Adjusting token amounts in financial contracts.

When to use it

Use the multiplication function when you need to:

• Perform basic multiplication in your contract logic.
• Scale values proportionally.
• Calculate compound values or rates.
• Implement mathematical formulas that involve multiplication.

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

Let's implement a simple token vesting contract that uses multiplication to calculate vested amounts:

;; Define constants
(define-constant VESTING_PERIOD u365)  ;; 1 year in days
(define-constant TOTAL_ALLOCATION u1000000)  ;; Total tokens to vest

;; Define data variables
(define-data-var startTime uint u0)
(define-data-var beneficiary principal tx-sender)

;; Function to initialize vesting
(define-public (start-vesting (recipient principal))
  (begin
    (asserts! (is-eq tx-sender (var-get beneficiary)) (err u1))
    (var-set startTime block-height)
    (var-set beneficiary recipient)
    (ok true)
  )
)

;; Function to calculate vested amount
(define-read-only (get-vested-amount)
  (let
    (
      (elapsed-time (- block-height (var-get startTime)))
      (vesting-rate (/ TOTAL_ALLOCATION VESTING_PERIOD))
    )
    (if (>= elapsed-time VESTING_PERIOD)
      TOTAL_ALLOCATION
      (* vesting-rate elapsed-time)
    )
  )
)

;; Function to claim vested tokens
(define-public (claim-tokens)
  (let
    (
      (vested-amount (get-vested-amount))
    )
    (asserts! (> vested-amount u0) (err u2))
    ;; Here you would typically transfer tokens
    ;; For simplicity, we're just returning the amount
    (ok vested-amount)
  )
)

This example demonstrates:

1. Using multiplication to calculate the vested amount based on elapsed time and vesting rate.
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

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

• /: Used for division operations.
• +: Used for addition operations.
• -: Used for subtraction operations.
• mul-overflow?: Used for checked multiplication with overflow detection.

Conclusion

The multiplication function is a fundamental tool for performing arithmetic operations in Clarity smart contracts. By understanding its behavior with different types of inputs and potential edge cases, developers can use it effectively to implement various mathematical operations in their contracts, from simple scaling to more complex financial calculations.