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:

Performing basic arithmetic calculations within smart contracts.
Scaling values, such as calculating fees or interest.
Implementing more complex mathematical operations.
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 start-time 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 start-time 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 start-time)))
      (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:

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

Common Pitfalls

Overlooking potential overflow when multiplying large numbers.
Not considering the effect of integer division when combined with multiplication.
Assuming 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