Hiro Docs

Using the multiplication function for arithmetic operations in Clarity smart contracts.

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:

1Performing basic arithmetic calculations within smart contracts.
2Scaling values, such as calculating fees or interest.
3Implementing more complex mathematical operations.
4Adjusting 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:

1Using multiplication to calculate the vested amount based on elapsed time and vesting rate.
2Combining multiplication with division to implement a linear vesting schedule.
3Using multiplication as part of a larger mathematical formula in a smart contract context.

Common Pitfalls

1Overlooking potential overflow when multiplying large numbers.
2Not considering the effect of integer division when combined with multiplication.
3Assuming multiplication always increases a value (forgetting about multiplication by fractions < 1 in integer arithmetic).

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

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.

multiply