Types reference

Clarity uses a strong static type system. Function arguments and database schemas require specified types, and all types are known at publish time.

Primitive types

int

Signed 128-bit integer. Ranges from -2^127 to 2^127 - 1.

(define-constant my-int -10)
(define-constant max-int 170141183460469231731687303715884105727)

uint

Unsigned 128-bit integer. Ranges from 0 to 2^128 - 1.

(define-constant my-uint u10)
(define-constant max-uint u340282366920938463463374607431768211455)

bool

Boolean value representing true or false.

(define-constant is-active true)
(define-constant is-disabled false)

principal

Represents an object that can have a token balance. Can be a standard principal (user address) or contract principal.

;; Standard principal
'ST1PQHQKV0RJXZFY1DGX8MNSNYVE3VGZJSRTPGZGM

;; Contract principal
'ST1PQHQKV0RJXZFY1DGX8MNSNYVE3VGZJSRTPGZGM.contract-name

Sequence types

(buff max-len)

Byte buffer with a maximum length. Used for arbitrary binary data.

(define-constant my-buff 0x68656c6c6f) ;; "hello" in hex
(define-data-var message (buff 20) 0x00)

(string-ascii max-len)

ASCII string with maximum length. Only supports ASCII characters.

(define-constant name (string-ascii 50) "Clarity")
(define-data-var user-name (string-ascii 100) "")

(string-utf8 max-len)

UTF-8 string with maximum length. Supports Unicode characters.

(define-constant greeting (string-utf8 50) u"Hello L! =�")
(define-data-var status-message (string-utf8 280) u"")

(list max-len entry-type)

Homogeneous list with specified maximum length and entry type.

(define-constant numbers (list 5 uint) (list u1 u2 u3 u4 u5))
(define-data-var prices (list 100 uint) (list))

Composite types

Tuple

Record with named fields. Each field has a specified type.

{
  name: (string-ascii 50),
  age: uint,
  active: bool
}

;; Example usage
(define-constant user {
  name: "Alice",
  age: u30,
  active: true
})

Tuples are commonly used for:

Returning multiple values from functions
Structuring complex data
Map keys and values

Special types

(optional type)

Represents a value that might not exist. Can be (some value) or none.

(define-data-var winner (optional principal) none)

;; Set value
(var-set winner (some 'ST1PQHQKV0RJXZFY1DGX8MNSNYVE3VGZJSRTPGZGM))

;; Check value
(match (var-get winner)
  user (print user)
  (print "No winner yet")
)

(response ok-type err-type)

Used by public functions to indicate success or failure. Successful responses commit state changes, while error responses abort all changes.

(define-public (divide (a uint) (b uint))
  (if (is-eq b u0)
    (err u1) ;; Division by zero error
    (ok (/ a b))
  )
)

Response types enable:

Atomic transaction semantics
Composable error handling
Clear success/failure paths

Type signatures

Functions must specify complete type signatures:

;; Read-only function
(define-read-only (get-balance (user principal))
  (response uint uint)
  ;; Function body
)

;; Public function
(define-public (transfer (amount uint) (recipient principal))
  (response bool uint)
  ;; Function body
)

;; Private function
(define-private (validate-amount (amount uint))
  bool
  ;; Function body
)

Type inference

While Clarity requires explicit type annotations for function signatures and data declarations, it can infer types within function bodies:

(define-read-only (calculate)
  (let ((x 10)        ;; Inferred as int
        (y u20)       ;; Inferred as uint
        (name "Test")) ;; Inferred as string-ascii
    (ok x))
)

Type safety

Clarity's type system prevents many common programming errors at publish time, before any code is executed. This includes type mismatches, null pointer exceptions, and buffer overflows.