# 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¶

`create_forwarder_to`(target: address, value: uint256 = 0[, salt: bytes32]) → address

Deploys a small contract that duplicates the logic of the contract at `target`, but has it’s 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) → 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 remainaing 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`)

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`.

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
```
`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)
```
`selfdestruct`(to: address) → None

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`(to: address, value: uint256) → None

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¶

`ecadd`(a: uint256, b: uint256) → uint256

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 (`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

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) → int128

Round a decimal up to the nearest integer.

• `value`: Decimal value to round up
```@external
@view
def foo(value: decimal) -> uint256:
return ceil(value)
```
```>>> ExampleContract.foo(3.1337)
4
```
`floor`(value: decimal) → int128

Round a decimal down to the nearest integer.

• `value`: Decimal value to round down
```@external
@view
def foo(value: decimal) -> uint256:
return floor(value)
```
```>>> ExampleContract.foo(3.1337)
3
```
`max`(a: numeric, b: numeric) → numeric

Return the creater 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 the same 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 the same 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
```

## 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 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>]

BETA, USE WITH CARE. 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,)`. 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 = "234"
return _abi_encode(x, y, method_id=method_id("foo()"))
```
```>>> ExampleContract.foo().hex()
"c2985578"
"0000000000000000000000000000000000000000000000000000000000000001"
"0000000000000000000000000000000000000000000000000000000000000040"
"0000000000000000000000000000000000000000000000000000000000000003"
"3233340000000000000000000000000000000000000000000000000000000000"
```
{"ft_lang_label":"__label__en","ft_lang_prob":0.5397318,"math_prob":0.9174552,"size":15111,"snap":"2021-31-2021-39","text_gpt3_token_len":4479,"char_repetition_ratio":0.2075197,"word_repetition_ratio":0.15166976,"special_character_ratio":0.35768646,"punctuation_ratio":0.1876877,"nsfw_num_words":0,"has_unicode_error":false,"math_prob_llama3":0.9747212,"pos_list":[0],"im_url_duplicate_count":[null],"WARC_HEADER":"{\"WARC-Type\":\"response\",\"WARC-Date\":\"2021-09-28T20:37:02Z\",\"WARC-Record-ID\":\"<urn:uuid:5d02a964-4d96-4bbf-8773-87eb9a73eafe>\",\"Content-Length\":\"84303\",\"Content-Type\":\"application/http; msgtype=response\",\"WARC-Warcinfo-ID\":\"<urn:uuid:d502b75f-b898-48f8-b1f2-862f3358346b>\",\"WARC-Concurrent-To\":\"<urn:uuid:fcc6cafa-9d8c-4a17-a8de-16e1aaaa0bcb>\",\"WARC-IP-Address\":\"104.17.32.82\",\"WARC-Target-URI\":\"https://vyper.readthedocs.io/en/latest/built-in-functions.html\",\"WARC-Payload-Digest\":\"sha1:FO4BWDZCVALADPDRBG4CFUDFSUZBDOEC\",\"WARC-Block-Digest\":\"sha1:3NIQ7JHDTOWSCSMQBSMEK6D2QJZMCDAM\",\"WARC-Identified-Payload-Type\":\"text/html\",\"warc_filename\":\"/cc_download/warc_2021/CC-MAIN-2021-39/CC-MAIN-2021-39_segments_1631780060882.17_warc_CC-MAIN-20210928184203-20210928214203-00200.warc.gz\"}"}