Primitive types are the most basic components. These are: signed and unsigned integers, booleans, and principals.
int, short for (signed) integer. These are 128 bits numbers that can either
be positive or negative. The minimum value is -2127 and the maximum value is
2127 - 1. Some examples:
uint, short for unsigned integer. These are 128 bits numbers that can only
be positive. The minimum value is therefore 0 and the maximum value is
2128 - 1. Unsigned integers are always prefixed by the character
Clarity has many built-in functions that accept either signed or unsigned integers.
(+ u2 u3)
(- 5 10)
(* u2 u16)
(/ 100 4)
As you might have noticed by now, integers are always whole numbers—there are no decimal points. It is something to keep in mind when writing your code.
(/ u10 u3)
If you punch the above into a calculator, you will likely get
Not with integers! The above expression evaluates to
u3, the decimals are
There are many more functions that take integers as inputs. We will get to the rest later in the book.
bool, short for boolean. A boolean value is either
are used to check if a certain condition is met or unmet (true or false). Some
built-in functions that accept booleans:
not (inverts a boolean):
true if all inputs are
(and true true true)
true if at least one input is
(or false true false)
A principal is a special type in Clarity and represents a Stacks address on
the blockchain. It is a unique identifier you can roughly equate to an email
address or bank account number—although definitely not the same! You might have
also heard the term wallet address as well. Clarity admits two different kinds
of principals: standard principals and contract principals. Standard
principals are backed by a corresponding private key whilst contract principals
point to a smart contract. Principals follow a specific structure and always
start with the characters
SP for the Stacks mainnet and
ST for the testnet
A literal principal value is prefixed by a single quote (
') in Clarity. Notice
there is no closing single quote.
Contract principals are a compound of the standard principal that deployed the contract and the contract name, delimited by a dot:
You will use the principal type often when writing Clarity. It is used to check who is calling the contract, recording information about different principals, function calls across contracts, and much more.
To retrieve the current STX balance of a principal, we can pass it to the
Both kinds of principals can hold tokens, we can thus also check the balance of a contract.
Zero balances are a little boring, so let us send some some STX to a principal:
(stx-transfer? u500 tx-sender 'ST1HTBVD3JG9C05J7HBJTHGR0GGW7KXW28M5JS8QE)
Knowing about primitives, and the fact that types can never mix, it is now clear
why the example in the previous section does not work. Since the first number is
a signed integer and the next one is an _unsigned integer_—notice the
analyser rejects the code as invalid. We should provide it with two signed or
two unsigned integers instead.
(+ 2 u3)
(+ u2 u3)