# Built in Functions¶

Vyper provides a collection of built in functions available in the global namespace of all contracts.

## Bitwise Operations¶

bitwise_and(x: uint256, y: uint256) uint256

Perform a “bitwise and” operation. Each bit of the output is 1 if the corresponding bit of `x` AND of `y` is 1, otherwise it’s 0.

```@external
@view
def foo(x: uint256, y: uint256) -> uint256:
return bitwise_and(x, y)
```
```>>> ExampleContract.foo(31337, 8008135)
12353
```
bitwise_not(x: uint256) uint256

Return the complement of `x` - the number you get by switching each 1 for a 0 and each 0 for a 1.

```@external
@view
def foo(x: uint256) -> uint256:
return bitwise_not(x)
```
```>>> ExampleContract.foo(0)
115792089237316195423570985008687907853269984665640564039457584007913129639935
```
bitwise_or(x: uint256, y: uint256) uint256

Perform a “bitwise or” operation. Each bit of the output is 0 if the corresponding bit of `x` AND of `y` is 0, otherwise it’s 1.

```@external
@view
def foo(x: uint256, y: uint256) -> uint256:
return bitwise_or(x, y)
```
```>>> ExampleContract.foo(31337, 8008135)
8027119
```
bitwise_xor(x: uint256, y: uint256) uint256

Perform a “bitwise exclusive or” operation. Each bit of the output is the same as the corresponding bit in `x` if that bit in `y` is 0, and it’s the complement of the bit in `x` if that bit in `y` is 1.

```@external
@view
def foo(x: uint256, y: uint256) -> uint256:
return bitwise_xor(x, y)
```
```>>> ExampleContract.foo(31337, 8008135)
8014766
```
shift(x: uint256, _shift: int128) uint256

Return `x` with the bits shifted `_shift` places. A positive `_shift` value equals a left shift, a negative value is a right shift.

```@external
@view
def foo(x: uint256, y: int128) -> uint256:
return shift(x, y)
```
```>>> ExampleContract.foo(2, 8)
512
```

## Chain Interaction¶

Deploys a small contract that duplicates the logic of the contract at `target`, but has its own state since every call to `target` is made using `DELEGATECALL` to `target`. To the end user, this should be indistinguishable from an independantly deployed contract with the same code as `target`.

Note

It is very important that the deployed contract at `target` is code you know and trust, and does not implement the `selfdestruct` opcode as this will affect the operation of the forwarder contract.

• `target`: Address of the contract to duplicate

• `value`: The wei value to send to the new contract address (Optional, default 0)

• `salt`: A `bytes32` value utilized by the `CREATE2` opcode (Optional, if supplied deterministic deployment is done via `CREATE2`)

Returns the address of the duplicated contract.

```@external
return create_forwarder_to(_target)
```
raw_call(to: address, data: Bytes, max_outsize: int = 0, gas: uint256 = gasLeft, value: uint256 = 0, is_delegate_call: bool = False, is_static_call: bool = False, revert_on_failure: bool = True) Bytes[max_outsize]

Call to the specified Ethereum address.

• `to`: Destination address to call to

• `data`: Data to send to the destination address

• `max_outsize`: Maximum length of the bytes array returned from the call. If the returned call data exceeds this length, only this number of bytes is returned.

• `gas`: The amount of gas to attach to the call. If not set, all remaining gas is forwarded.

• `value`: The wei value to send to the address (Optional, default `0`)

• `is_delegate_call`: If `True`, the call will be sent as `DELEGATECALL` (Optional, default `False`)

• `is_static_call`: If `True`, the call will be sent as `STATICCALL` (Optional, default `False`)

• `revert_on_failure`: If `True`, the call will revert on a failure, otherwise `success` will be returned (Optional, default `True`)

Returns the data returned by the call as a `Bytes` list, with `max_outsize` as the max length.

Returns `None` if `max_outsize` is omitted or set to `0`.

Returns `success` in a tuple if `revert_on_failure` is set to `False`.

Note

The actual size of the returned data may be less than `max_outsize`. You can use `len` to obtain the actual size.

Returns the address of the duplicated contract.

```@external
@payable
response: Bytes = raw_call(_target, 0xa9059cbb, max_outsize=32, value=msg.value)
return response

@external
@payable
success: bool = False
response: Bytes = b""
success, response = raw_call(_target, 0xa9059cbb, max_outsize=32, value=msg.value, revert_on_failure=False)
assert success
return response
```
raw_log(topics: bytes32, data: Union[Bytes, bytes32]) None

Provides low level access to the `LOG` opcodes, emitting a log without having to specify an ABI type.

• `topics`: List of `bytes32` log topics. The length of this array determines which opcode is used.

• `data`: Unindexed event data to include in the log. May be given as `Bytes` or `bytes32`.

```@external
def foo(_topic: bytes32, _data: Bytes):
raw_log([_topic], _data)
```

Trigger the `SELFDESTRUCT` opcode (`0xFF`), causing the contract to be destroyed.

• `to`: Address to forward the contract’s ether balance to

Warning

This method delete the contract from the blockchain. All non-ether assets associated with this contract are “burned” and the contract is no longer accessible.

```@external
def do_the_needful():
selfdestruct(msg.sender)
```

Send ether from the contract to the specified Ethereum address.

• `to`: The destination address to send ether to

• `value`: The wei value to send to the address

Note

The amount to send is always specified in `wei`.

```@external
```

## Cryptography¶

Take two points on the Alt-BN128 curve and add them together.

```@external
@view
def foo(x: uint256, y: uint256) -> uint256:
```
```>>> ExampleContract.foo([1, 2], [1, 2])
[
1368015179489954701390400359078579693043519447331113978918064868415326638035,
9918110051302171585080402603319702774565515993150576347155970296011118125764,
]
```
ecmul(point: uint256, scalar: uint256) uint256

Take a point on the Alt-BN128 curve (`p`) and a scalar value (`s`), and return the result of adding the point to itself `s` times, i.e. `p * s`.

• `point`: Point to be multiplied

• `scalar`: Scalar value

```@external
@view
def foo(point: uint256, scalar: uint256) -> uint256:
return ecmul(point, scalar)
```
```>>> ExampleContract.foo([1, 2], 3)
[
3353031288059533942658390886683067124040920775575537747144343083137631628272,
19321533766552368860946552437480515441416830039777911637913418824951667761761,
]
```
ecrecover(hash: bytes32, v: uint256, r: uint256, s: uint256) address

Recover the address associated with the public key from the given elliptic curve signature.

• `r`: first 32 bytes of signature

• `s`: second 32 bytes of signature

• `v`: final 1 byte of signature

Returns the associated address, or `0` on error.

```@external
@view
def foo(hash: bytes32, v: uint256, r:uint256, s:uint256) -> address:
return ecrecover(hash, v, r, s)
```
```>>> ExampleContract.foo('0x6c9c5e133b8aafb2ea74f524a5263495e7ae5701c7248805f7b511d973dc7055',
28,
78616903610408968922803823221221116251138855211764625814919875002740131251724,
37668412420813231458864536126575229553064045345107737433087067088194345044408
)
```
keccak256(_value) bytes32

Return a `keccak256` hash of the given value.

• `_value`: Value to hash. Can be a literal string, `Bytes`, or `bytes32`.

```@external
@view
def foo(_value: Bytes) -> bytes32
return keccak256(_value)
```
```>>> ExampleContract.foo(b"potato")
0x9e159dfcfe557cc1ca6c716e87af98fdcb94cd8c832386d0429b2b7bec02754f
```
sha256(_value) bytes32

Return a `sha256` (SHA2 256bit output) hash of the given value.

• `_value`: Value to hash. Can be a literal string, `Bytes`, or `bytes32`.

```@external
@view
def foo(_value: Bytes) -> bytes32
return sha256(_value)
```
```>>> ExampleContract.foo(b"potato")
```

## Data Manipulation¶

concat(a, b, *args) Union[Bytes, String]

Take 2 or more bytes arrays of type `bytes32`, `Bytes` or `String` and combine them into a single value.

If the input arguments are `String` the return type is `String`. Otherwise the return type is `Bytes`.

```@external
@view
def foo(a: String, b: String, c: String) -> String:
return concat(a, " ", b, " ", c, "!")
```
```>>> ExampleContract.foo("why","hello","there")
"why hello there!"
```
convert(value, type_) Any

Converts a variable or literal from one type to another.

• `value`: Value to convert

• `type_`: The destination type to convert to (e.g., `bool`, `decimal`, `int128`, `uint256` or `bytes32`)

Returns a value of the type specified by `type_`.

For more details on available type conversions, see Type Conversions.

extract32(b: Bytes, start: int128, output_type=bytes32) Any

Extract a value from a `Bytes` list.

• `b`: `Bytes` list to extract from

• `start`: Start point to extract from

• `output_type`: Type of output (`bytes32`, `int128`, or `address`). Defaults to `bytes32`.

Returns a value of the type specified by `output_type`.

```@external
@view
```
```>>> ExampleContract.foo("0x0000000000000000000000009f8F72aA9304c8B593d555F12eF6589cC3A579A2")
"0x9f8F72aA9304c8B593d555F12eF6589cC3A579A2"
```
slice(b: Union[Bytes, bytes32, String], start: uint256, length: uint256) Union[Bytes, String]

Copy a list of bytes and return a specified slice.

• `b`: value being sliced

• `start`: start position of the slice

• `length`: length of the slice, must be constant. Immutables and variables are not supported.

If the value being sliced is a `Bytes` or `bytes32`, the return type is `Bytes`. If it is a `String`, the return type is `String`.

```@external
@view
def foo(s: String) -> String:
return slice(s, 4, 5)
```
```>>> ExampleContract.foo("why hello! how are you?")
"hello"
```

## Math¶

abs(value: int256) int256

Return the absolute value of a signed integer.

• `value`: Integer to return the absolute value of

```@external
@view
def foo(value: int256) -> int256:
return abs(value)
```
```>>> ExampleContract.foo(-31337)
31337
```
ceil(value: decimal) int256

Round a decimal up to the nearest integer.

• `value`: Decimal value to round up

```@external
@view
def foo(x: decimal) -> int256:
return ceil(x)
```
```>>> ExampleContract.foo(3.1337)
4
```
floor(value: decimal) int256

Round a decimal down to the nearest integer.

• `value`: Decimal value to round down

```@external
@view
def foo(x: decimal) -> int256:
return floor(x)
```
```>>> ExampleContract.foo(3.1337)
3
```
max(a: numeric, b: numeric) numeric

Return the greater value of `a` and `b`. The input values may be any numeric type as long as they are both of the same type. The output value is of the same type as the input values.

```@external
@view
def foo(a: uint256, b: uint256) -> uint256:
return max(a, b)
```
```>>> ExampleContract.foo(23, 42)
42
```
min(a: numeric, b: numeric) numeric

Returns the lesser value of `a` and `b`. The input values may be any numeric type as long as they are both of the same type. The output value is of the same type as the input values.

```@external
@view
def foo(a: uint256, b: uint256) -> uint256:
return min(a, b)
```
```>>> ExampleContract.foo(23, 42)
23
```
pow_mod256(a: uint256, b: uint256) uint256

Return the result of `a ** b % (2 ** 256)`.

This method is used to perform exponentiation without overflow checks.

```@external
@view
def foo(a: uint256, b: uint256) -> uint256:
return pow_mod256(a, b)
```
```>>> ExampleContract.foo(2, 3)
8
>>> ExampleContract.foo(100, 100)
59041770658110225754900818312084884949620587934026984283048776718299468660736
```
sqrt(d: decimal) decimal

Return the square root of the provided decimal number, using the Babylonian square root algorithm.

```@external
@view
def foo(d: decimal) -> decimal:
return sqrt(d)
```
```>>> ExampleContract.foo(9.0)
3.0
```
uint256_addmod(a: uint256, b: uint256, c: uint256) uint256

Return the modulo of `(a + b) % c`. Reverts if `c == 0`.

```@external
@view
def foo(a: uint256, b: uint256, c: uint256) -> uint256:
```
```>>> (6 + 13) % 8
3
>>> ExampleContract.foo(6, 13, 8)
3
```
uint256_mulmod(a: uint256, b: uint256, c: uint256) uint256

Return the modulo from `(a * b) % c`. Reverts if `c == 0`.

```@external
@view
def foo(a: uint256, b: uint256, c: uint256) -> uint256:
return uint256_mulmod(a, b, c)
```
```>>> (11 * 2) % 5
2
>>> ExampleContract.foo(11, 2, 5)
2
```

Add `x` and `y`, without checking for overflow. `x` and `y` must both be integers of the same type. If the result exceeds the bounds of the input type, it will be wrapped.

```@external
@view
def foo(x: uint8, y: uint8) -> uint8:

@external
@view
def bar(x: int8, y: int8) -> int8:
```
```>>> ExampleContract.foo(1, 1)
2

>>> ExampleContract.foo(255, 255)
254

>>> ExampleContract.bar(127, 127)
-2
```

Note

Performance note: for the native word types of the EVM `uint256` and `int256`, this will compile to a single `ADD` instruction, since the EVM natively wraps addition on 256-bit words.

unsafe_sub(x: integer, y: integer) integer

Subtract `x` and `y`, without checking for overflow. `x` and `y` must both be integers of the same type. If the result underflows the bounds of the input type, it will be wrapped.

```@external
@view
def foo(x: uint8, y: uint8) -> uint8:
return unsafe_sub(x, y)

@external
@view
def bar(x: int8, y: int8) -> int8:
return unsafe_sub(x, y)
```
```>>> ExampleContract.foo(4, 3)
1

>>> ExampleContract.foo(0, 1)
255

>>> ExampleContract.bar(-128, 1)
127
```

Note

Performance note: for the native word types of the EVM `uint256` and `int256`, this will compile to a single `SUB` instruction, since the EVM natively wraps subtraction on 256-bit words.

unsafe_mul(x: integer, y: integer) integer

Multiply `x` and `y`, without checking for overflow. `x` and `y` must both be integers of the same type. If the result exceeds the bounds of the input type, it will be wrapped.

```@external
@view
def foo(x: uint8, y: uint8) -> uint8:
return unsafe_mul(x, y)

@external
@view
def bar(x: int8, y: int8) -> int8:
return unsafe_mul(x, y)
```
```>>> ExampleContract.foo(1, 1)
1

>>> ExampleContract.foo(255, 255)
1

>>> ExampleContract.bar(-128, -128)
0

>>> ExampleContract.bar(127, -128)
-128
```

Note

Performance note: for the native word types of the EVM `uint256` and `int256`, this will compile to a single `MUL` instruction, since the EVM natively wraps multiplication on 256-bit words.

unsafe_div(x: integer, y: integer) integer

Divide `x` and `y`, without checking for division-by-zero. `x` and `y` must both be integers of the same type. If the denominator is zero, the result will (following EVM semantics) be zero.

```@external
@view
def foo(x: uint8, y: uint8) -> uint8:
return unsafe_div(x, y)

@external
@view
def bar(x: int8, y: int8) -> int8:
return unsafe_div(x, y)
```
```>>> ExampleContract.foo(1, 1)
1

>>> ExampleContract.foo(1, 0)
0

>>> ExampleContract.bar(-128, -1)
-128
```

Note

Performance note: this will compile to a single `SDIV` or `DIV` instruction, depending on if the inputs are signed or unsigned (respectively).

## Utilities¶

as_wei_value(_value, unit: str) uint256

Take an amount of ether currency specified by a number and a unit and return the integer quantity of wei equivalent to that amount.

• `_value`: Value for the ether unit. Any numeric type may be used, however the value cannot be negative.

• `unit`: Ether unit name (e.g. `"wei"`, `"ether"`, `"gwei"`, etc.) indicating the denomination of `_value`. Must be given as a literal string.

```@external
@view
def foo(s: String) -> uint256:
return as_wei_value(1.337, "ether")
```
```>>> ExampleContract.foo(1)
1337000000000000000
```
blockhash(block_num: uint256) bytes32

Return the hash of the block at the specified height.

Note

The EVM only provides access to the most recent 256 blocks. This function returns `EMPTY_BYTES32` if the block number is greater than or equal to the current block number or more than 256 blocks behind the current block.

```@external
@view
def foo() -> bytes32:
return blockhash(block.number - 16)
```
```>>> ExampleContract.foo()
0xf3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
```
empty(typename) Any

Return a value which is the default (zeroed) value of its type. Useful for initializing new memory variables.

• `typename`: Name of the type

```@external
@view
def foo():
x: uint256 = empty(uint256)
```
len(b: Union[Bytes, String]) uint256

Return the length of a given `Bytes` or `String`.

```@external
@view
def foo(s: String) -> uint256:
return len(s)
```
```>>> ExampleContract.foo("hello")
5
```
method_id(method, output_type: type = Bytes) Union[bytes32, Bytes]

Takes a function declaration and returns its method_id (used in data field to call it).

• `method`: Method declaration as given as a literal string

• `output_type`: The type of output (`Bytes` or `bytes32`). Defaults to `Bytes`.

Returns a value of the type specified by `output_type`.

```@external
@view
def foo() -> Bytes:
```
```>>> ExampleContract.foo()
```
_abi_encode(*args, ensure_tuple: bool = True) Bytes[<depends on input>]

Takes a variable number of args as input, and returns the ABIv2-encoded bytestring. Used for packing arguments to raw_call, EIP712 and other cases where a consistent and efficient serialization method is needed. Once this function has seen more use we provisionally plan to put it into the `ethereum.abi` namespace.

• `*args`: Arbitrary arguments

• `ensure_tuple`: If set to True, ensures that even a single argument is encoded as a tuple. In other words, `bytes` gets encoded as `(bytes,)`, and `(bytes,)` gets encoded as `((bytes,),)` This is the calling convention for Vyper and Solidity functions. Except for very specific use cases, this should be set to True. Must be a literal.

• `method_id`: A literal hex or Bytes value to append to the beginning of the abi-encoded bytestring.

Returns a bytestring whose max length is determined by the arguments. For example, encoding a `Bytes` results in a `Bytes` (first word is the length of the bytestring variable).

```@external
@view
def foo() -> Bytes:
x: uint256 = 1
y: Bytes = b"234"
return _abi_encode(x, y, method_id=method_id("foo()"))
```
```>>> ExampleContract.foo().hex()
"c2985578"
"0000000000000000000000000000000000000000000000000000000000000001"
"0000000000000000000000000000000000000000000000000000000000000040"
"0000000000000000000000000000000000000000000000000000000000000003"
"3233340000000000000000000000000000000000000000000000000000000000"
```