examples

Test suite containing examples that demonstrate how the library can be used to synthesize circuits from functions.

To view the source code of an example function, click its [source] link. These examples (as well as additional background information) are discussed in more detail in a relevant report.

test.test_circuitry.equal(x: bit⁣, y: bit⁣) → bit⁣

Function that performs a simple single-bit equality calculation using logical and arithmetic operations.

The synthesized circuit object is introduced as an attribute of the function and can be evaluated on two bit values (as indicated by the function’s type annotation).

>>> equal.circuit.evaluate([[0], [1]])
[[0]]

Note that the function itself can still be invoked on its own in the usual manner if the supplied inputs are integers or bit instances. When the function is invoked in this way, the output of the function corresponds to its output type annotation.

>>> equal(0, 1)
0
>>> b = equal(bit(0), bit(1))
>>> isinstance(b, bit)
True
>>> int(b)
0

test.test_circuitry.equals_iterative(xs: bits(8), ys: bits(8)) → bit

Function that employs an iterative approach and performs a bit vector equality calculation. This function invokes both the single-bit equality function defined above and the logical conjunction operation.

>>> bs = [0, 1, 1, 0, 1, 0, 1, 0]
>>> equals_iterative.circuit.evaluate([bs, bs])
[[1]]
>>> equals_iterative.circuit.evaluate([bs, list(reversed(bs))])
[[0]]

test.test_circuitry.equals_functional(xs: bits(8), ys: bits(8)) → bit

Function that employs a functional approach and performs a bit vector equality calculation. This function invokes both the single-bit equality function defined above and the logical conjunction operation.

>>> bs = [0, 1, 1, 0, 1, 0, 1, 0]
>>> equals_functional.circuit.evaluate([bs, bs])
[[1]]
>>> equals_functional.circuit.evaluate([bs, list(reversed(bs))])
[[0]]

test.test_circuitry.add32(xs, ys)

Function that performs addition of two interegers that are represented as 32-bit vectors. This function is intended for use by the sha256 function that implements SHA-256.

Note that this is a helper function that is invoked by the sha256 function. It is not decorated because execution of sha256 is what synthesizes the overall SHA-256 circuit. The body of this function could have been inlined within the body of the sha256 function without impacting the synthesis of the SHA-256 circuit.

test.test_circuitry.sha256_iteration(d_8_32s, m_64_8s)

Perform a single iteration of the SHA-256 digest computation on the current digest (consisting of 32 distinct bit vectors, each having 8 bits) based on a message portion (consisting of 64 distinct bit vectors, each having 8 bits) to produce the next digest.

Note that this is a helper function that is invoked by the sha256 function. It is not decorated because execution of sha256 is what synthesizes the overall SHA-256 circuit. The body of this function could have been inlined within the body of the sha256 function without impacting the synthesis of the SHA-256 circuit.

test.test_circuitry.sha256(message: bits(512)⁣) → bits(256)⁣

Accept an appropriately padded bit vector of length 512 and compute a SHA-256 message digest as the output (represented as a bit vector having 256 bits).

This SHA-256 algorithm conforms to the FIPS 180-4 specification and expects inputs that are appropriately padded. The example below demonstrates how an appropriate input byte vector can be constructed for the synthesized circuit.

>>> input_bytes = bytes([1, 2, 3])
>>> input_padding = (
...     bytes([128] + ([0] * (55 - len(input_bytes)))) +
...     int(8 * len(input_bytes)).to_bytes(8, 'big')
... )

When evaluating the synthesized circuit, the input must be converted into a bit vector. Note that the output consists of a list containing a single bit vector that has 256 bits.

>>> [output_bits] = sha256.circuit.evaluate([
...     [
...         b
...         for byte in (input_bytes + input_padding)
...         for b in bitlist(byte, 8)
...     ]
... ])

The output can be compared to a reference implementation.

>>> bitlist(output_bits).hex() == hashlib.sha256(input_bytes).hexdigest()
True