@deroll/cmio 0.1.0

package/deps/machine-guest-tools/sys-utils/libcmt/include/libcmt/io.h

@@ -0,0 +1,168 @@
+/* Copyright Cartesi and individual authors (see AUTHORS)
+ * SPDX-License-Identifier: Apache-2.0
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/** @file
+ * @defgroup libcmt_io_driver Cartesi Machine Input/Output Driver
+ * Low level abstraction of the Cartesi Machine kernel driver.
+ *
+ * Interaction is as follows:
+ * - Open the kernel device and mmap the shared memory ranges (tx and rx) with:
+ *   @ref cmt_io_init.
+ * - Retrieve the memory regions from the library with: @ref cmt_io_get_tx and
+ *   @ref cmt_io_get_rx.
+ * - Do requests (next input, emit output ...) by yielding the control back to
+ *   the emulator with: @ref cmt_io_yield.
+ *
+ * Lets look at some code:
+ *
+ * @include examples/io.c
+ *
+ * There are two implementations provided: `ioctl` that interacts with the
+ * cartesi-machine linux driver and `mock` that reads and writes the host
+ * filesystem, used for testing.
+ *
+ * @section Environment variables
+ *
+ * this module exposes two environment variables: @p CMT_DEBUG and @p CMT_INPUTS.
+ *
+ * @p CMT_DEBUG prints runtime information during application execution.
+ *
+ * ```
+ * CMT_DEBUG=yes ./application
+ * ```
+ *
+ * @p CMT_INPUTS feeds inputs to the mock (ignored for ioctl).
+ *
+ * ```
+ * CMT_INPUTS=0:advance.bin,1:inspect.bin ./application
+ * ```
+ *
+ * @ingroup libcmt
+ * @{ */
+#ifndef CMT_IO_H
+#define CMT_IO_H
+#include "buf.h"
+#include <stdint.h>
+
+/** Device */
+enum {
+    HTIF_DEVICE_YIELD = 2, /**< Yield device */
+};
+
+/** Commands */
+enum {
+    HTIF_YIELD_CMD_AUTOMATIC = 0, /**< Automatic yield */
+    HTIF_YIELD_CMD_MANUAL = 1,    /**< Manual yield */
+};
+
+/** Automatic reasons */
+enum {
+    HTIF_YIELD_AUTOMATIC_REASON_PROGRESS = 1,  /**< Progress */
+    HTIF_YIELD_AUTOMATIC_REASON_TX_OUTPUT = 2, /**< emit an output */
+    HTIF_YIELD_AUTOMATIC_REASON_TX_REPORT = 4, /**< emit a report */
+};
+
+/** Manual reasons */
+enum {
+    HTIF_YIELD_MANUAL_REASON_RX_ACCEPTED = 1,  /**< Accept and load next input */
+    HTIF_YIELD_MANUAL_REASON_RX_REJECTED = 2,  /**< Reject and revert */
+    HTIF_YIELD_MANUAL_REASON_TX_EXCEPTION = 4, /**< emit a exception and halt execution */
+};
+
+/** Reply reason when requesting @ref HTIF_YIELD_REASON_RX_ACCEPTED or HTIF_YIELD_REASON_RX_REJECTED */
+enum {
+    HTIF_YIELD_REASON_ADVANCE = 0, /**< Input is advance */
+    HTIF_YIELD_REASON_INSPECT = 1, /**< Input is inspect */
+};
+
+typedef struct {
+    cmt_buf_t tx[1];
+    cmt_buf_t rx[1];
+    int fd;
+} cmt_io_driver_ioctl_t;
+
+typedef struct {
+    cmt_buf_t tx[1];
+    cmt_buf_t rx[1];
+    cmt_buf_t inputs_left;
+
+    int input_type;
+    char input_filename[128];
+    char input_fileext[16];
+
+    int input_seq;
+    int output_seq;
+    int report_seq;
+    int exception_seq;
+    int gio_seq;
+} cmt_io_driver_mock_t;
+
+/** Implementation specific cmio state. */
+typedef union cmt_io_driver {
+    cmt_io_driver_ioctl_t ioctl;
+    cmt_io_driver_mock_t mock;
+} cmt_io_driver_t;
+
+/** yield struct cmt_io_yield */
+typedef struct cmt_io_yield {
+    uint8_t dev;
+    uint8_t cmd;
+    uint16_t reason;
+    uint32_t data;
+} cmt_io_yield_t;
+
+/** Open the io device and initialize the driver. Release its resources with @ref cmt_io_fini.
+ *
+ * @param [in] me A uninitialized @ref cmt_io_driver state
+ *
+ * @return
+ * |   |                             |
+ * |--:|-----------------------------|
+ * |  0| success                     |
+ * |< 0| failure with a -errno value | */
+int cmt_io_init(cmt_io_driver_t *me);
+
+/** Release the driver resources and close the io device.
+ *
+ * @param [in] me A successfully initialized state by @ref cmt_io_init
+ * @note usage of @p me after this call is a BUG and will cause undefined behaviour */
+void cmt_io_fini(cmt_io_driver_t *me);
+
+/** Retrieve the transmit buffer @p tx
+ *
+ * @param [in] me A successfully initialized state by @ref cmt_io_init
+ * @return
+ * - writable memory region as defined in the setup structure (check @ref cmt_buf_t)
+ * @note memory is valid until @ref cmt_io_fini is called. */
+cmt_buf_t cmt_io_get_tx(cmt_io_driver_t *me);
+
+/** Retrieve the receive buffer @p rx
+ *
+ * @param [in] me A successfully initialized state by @ref cmt_io_init
+ * @return
+ * - readable memory region as defined in the setup structure (check @ref cmt_buf_t)
+ * @note memory is valid until @ref cmt_io_fini is called. */
+cmt_buf_t cmt_io_get_rx(cmt_io_driver_t *me);
+
+/** Perform the yield encoded in @p rr.
+ *
+ * @param [in] me A successfully initialized state by @ref cmt_io_init
+ * @param [in,out] rr Request and Reply
+ * @return
+ * - 0 on success
+ * - negative errno code on error */
+int cmt_io_yield(cmt_io_driver_t *me, cmt_io_yield_t *rr);
+
+#endif /* CMT_IO_H */

package/deps/machine-guest-tools/sys-utils/libcmt/include/libcmt/keccak.h

@@ -0,0 +1,131 @@
+/* Copyright Cartesi and individual authors (see AUTHORS)
+ * SPDX-License-Identifier: Apache-2.0
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/** @file
+ * @defgroup libcmt_keccak keccak
+ * Keccak 256 digest
+ *
+ * Data can be inserted in pieces:
+ * @code
+ * ...
+ * uint8_t h[CMT_KECCAK_LENGTH];
+ * cmt_keccak_t st[1];
+ *
+ * cmt_keccak_init(st);
+ * cmt_keccak_update(st, 1, "h");
+ * cmt_keccak_update(st, 1, "e");
+ * cmt_keccak_update(st, 1, "l");
+ * cmt_keccak_update(st, 1, "l");
+ * cmt_keccak_update(st, 1, "o");
+ * cmt_keccak_final(st, h);
+ * ...
+ * @endcode
+ *
+ * all at once:
+ * @code
+ * ...
+ * const char data[] = "hello";
+ * uint8_t h[CMT_KECCAK_LENGTH];
+ * cmt_keccak_data(h, sizeof(data)-1, data);
+ * ...
+ * @endcode
+ *
+ * or with a specialized call to generate @ref funsel data:
+ * @code
+ * ...
+ * uint32_t funsel = cmt_keccak_funsel("FunctionCall(address,bytes)");
+ * ...
+ * @endcode
+ *
+ * Code based on https://github.com/mjosaarinen/tiny_sha3 with the sha3 to
+ * keccak change as indicated by this comment:
+ * https://github.com/mjosaarinen/tiny_sha3#updated-07-aug-15
+ *
+ * @ingroup libcmtcmt
+ * @{ */
+#ifndef CMT_KECCAK_H
+#define CMT_KECCAK_H
+#include <stddef.h>
+#include <stdint.h>
+
+enum {
+    CMT_KECCAK_LENGTH = 32, /**< Bytes in the hash digest */
+};
+
+/** Opaque internal keccak state */
+typedef union cmt_keccak_state {
+    uint8_t b[200];
+    uint64_t q[25];
+} cmt_keccak_state_t;
+
+/** Opaque Keccak state, used to do hash computations, initialize with:
+ * - @ref cmt_keccak_init
+ * - @ref CMT_KECCAK_INIT
+ * - @ref CMT_KECCAK_DECL */
+typedef struct cmt_keccak {
+    cmt_keccak_state_t st;
+    int pt, rsiz;
+} cmt_keccak_t;
+
+/** Initialize a @ref cmt_keccak_t hasher state.
+ *
+ * @param [out] state uninitialized @ref cmt_keccak_t */
+void cmt_keccak_init(cmt_keccak_t *state);
+
+/** Hash @b n bytes of @b data
+ *
+ * @param [in,out] state  initialize the hasher state
+ * @param [in]     length bytes in @b data to process
+ * @param [in]     data   data to hash */
+void cmt_keccak_update(cmt_keccak_t *state, size_t n, const void *data);
+
+/** Finalize the hash calculation from @b state and store it in @b md
+ *
+ * @param [in]  state initialize the hasher state (with all data already added to it)
+ * @param [out] md    32bytes to store the computed hash */
+void cmt_keccak_final(cmt_keccak_t *state, void *md);
+
+/** Hash all @b n bytes of @b data at once
+ *
+ * @param [in]  length bytes in @b data to process
+ * @param [in]  data   data to hash
+ * @param [out] md     32bytes to store the computed hash
+ * @return pointer to @b md
+ *
+ * Equivalent to:
+ * @code
+ * cmt_keccak_t st = CMT_KECCAK_INIT(&st);
+ * cmt_keccak_update(&st, n, data);
+ * cmt_keccak_final(&st, md);
+ * return md;
+ * @endcode */
+uint8_t *cmt_keccak_data(size_t length, const void *data, uint8_t md[CMT_KECCAK_LENGTH]);
+
+/** Compute the function selector from the solidity declaration @p decl
+ *
+ * @param [in]  decl   solidity call declaration, without variable names
+ * @param [out] funsel function selector as described by @ref funsel
+ * @return A @p funsel value as if defined by @ref CMT_ABI_FUNSEL
+ *
+ * Example usage:
+ * @code
+ * ...
+ * uint32_t funsel = cmt_keccak_funsel("FunctionCall(address,bytes)");
+ * ...
+ * @endcode
+ */
+uint32_t cmt_keccak_funsel(const char *decl);
+#endif /* CMT_KECCAK_H */
+/** $@} */

package/deps/machine-guest-tools/sys-utils/libcmt/include/libcmt/merkle.h

@@ -0,0 +1,118 @@
+/* Copyright Cartesi and individual authors (see AUTHORS)
+ * SPDX-License-Identifier: Apache-2.0
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/** @file
+ * @defgroup libcmt_merkle merkle
+ * merkle tree of keccak256 hashes
+ *
+ * @ingroup libcmt
+ * @{ */
+#ifndef CMT_MERKLE_H
+#define CMT_MERKLE_H
+#include "keccak.h"
+
+enum {
+    CMT_MERKLE_TREE_HEIGHT = 63, /**< merkle tree height */
+};
+
+/** Opaque Merkle tree state.
+ * initialize with: @ref cmt_merkle_init */
+typedef struct {
+    uint64_t leaf_count;                                      /**< number of leaves in tree */
+    uint8_t state[CMT_MERKLE_TREE_HEIGHT][CMT_KECCAK_LENGTH]; /**< hashes of complete subtrees */
+} cmt_merkle_t;
+
+/** Initialize a @ref cmt_merkle_t tree state.
+ *
+ * @param [in] me    uninitialized state */
+void cmt_merkle_init(cmt_merkle_t *me);
+
+/** Resets a @ref cmt_merkle_t to pristine conditions.
+ *
+ * @param [in] me    initialized state */
+void cmt_merkle_reset(cmt_merkle_t *me);
+
+/** Finalize a @ref cmt_merkle_t tree state.
+ *
+ * @param [in] me    initialized state
+ *
+ * @note use of @p me after this call is undefined behavior. */
+void cmt_merkle_fini(cmt_merkle_t *me);
+
+/** Load the a @ref cmt_merkle_t tree from a @p file handle.
+ *
+ * @param [in] me       either a initialized or uninitialized state
+ * @param [in] filepath which file to save the merkle state
+ *
+ * @return
+ * |   |                             |
+ * |--:|-----------------------------|
+ * |  0| success                     |
+ * |< 0| failure with a -errno value | */
+int cmt_merkle_load(cmt_merkle_t *me, const char *filepath);
+
+/** Save the a @ref cmt_merkle_t tree to a @p file handle.
+ *
+ * @param [in] me       either a initialized or uninitialized state
+ * @param [in] filepath which file to save the merkle state
+ *
+ * @return
+ * |   |                             |
+ * |--:|-----------------------------|
+ * |  0| success                     |
+ * |< 0| failure with a -errno value | */
+int cmt_merkle_save(cmt_merkle_t *me, const char *filepath);
+
+/** Return number of leaves already in tree
+ *
+ * @param [in,out] me initialized state
+ * @return
+ * - leaf count */
+uint64_t cmt_merkle_get_leaf_count(cmt_merkle_t *me);
+
+/** Append a leaf node
+ *
+ * @param [in,out] me initialized state
+ * @param [in] hash   value of the new leaf
+ *
+ * @return
+ * |          |                                 |
+ * |---------:|---------------------------------|
+ * |         0| success                         |
+ * | -ENOBUFS | indicates that the tree is full |
+ * |       < 0| failure with a -errno value     | */
+int cmt_merkle_push_back(cmt_merkle_t *me, const uint8_t hash[CMT_KECCAK_LENGTH]);
+
+/** Compute the keccak-256 hash of @p data and append it as a leaf node
+ *
+ * @param [in,out] me     initialized state
+ * @param [in]     length size of @p data in bytes
+ * @param [in]     data   array of bytes
+ *
+ * @return
+ * |          |                                 |
+ * |---------:|---------------------------------|
+ * |         0| success                         |
+ * | -ENOBUFS | indicates that the tree is full |
+ * |       < 0| failure with a -errno value     | */
+int cmt_merkle_push_back_data(cmt_merkle_t *me, size_t length, const void *data);
+
+/** Compute the root hash of the merkle tree
+ *
+ * @param [in]  me   initialized state
+ * @param [out] root root hash of the merkle tree */
+void cmt_merkle_get_root_hash(cmt_merkle_t *me, uint8_t root[CMT_KECCAK_LENGTH]);
+
+#endif /* CMT_MERKLE_H */

package/deps/machine-guest-tools/sys-utils/libcmt/include/libcmt/rollup.h

@@ -0,0 +1,260 @@
+/* Copyright Cartesi and individual authors (see AUTHORS)
+ * SPDX-License-Identifier: Apache-2.0
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/** @file
+ * @defgroup libcmt_rollup rollup
+ * Rollup abstraction layer
+ *
+ * Takes care of @ref libcmt_io_driver interactions, @ref libcmt_abi
+ * encoding/decoding and @ref libcmt_merkle tree handling.
+ *
+ * Mocked version has support for simulating I/O via environment variables:
+ * @p CMT_INPUTS="0:input.bin,..." and verbose output with @p CMT_DEBUG=yes.
+ *
+ * Lets look at some code:
+ *
+ * @include doc/examples/rollup.c
+ *
+ * @ingroup libcmt
+ * @{ */
+#ifndef CMT_ROLLUP_H
+#define CMT_ROLLUP_H
+#include "abi.h"
+#include "io.h"
+#include "merkle.h"
+
+typedef struct cmt_rollup {
+    union cmt_io_driver io[1];
+    uint32_t fromhost_data;
+    cmt_merkle_t merkle[1];
+
+    // cache merkle values and repeat them on finish when the tree doesn't change
+    uint8_t finish_root_hash[CMT_KECCAK_LENGTH];
+    uint64_t finish_leaf_count;
+} cmt_rollup_t;
+
+/** Public struct with the advance state contents */
+typedef struct cmt_rollup_advance {
+    uint64_t chain_id;                        /**< network */
+    cmt_abi_address_t app_contract;           /**< application contract address */
+    cmt_abi_address_t msg_sender;             /**< input sender address */
+    uint64_t block_number;                    /**< block number of this input */
+    uint64_t block_timestamp;                 /**< block timestamp of this input UNIX epoch format) */
+    cmt_abi_u256_t prev_randao;               /**< The latest RANDAO mix of the post beacon state of the previous block */
+    uint64_t index;                           /**< input index (in relation to all inputs ever sent to the DApp) */
+    cmt_abi_bytes_t payload;                  /**< payload for this input */
+} cmt_rollup_advance_t;
+
+/** Public struct with the inspect state contents */
+typedef struct cmt_rollup_inspect {
+    cmt_abi_bytes_t payload; /**< payload for this input */
+} cmt_rollup_inspect_t;
+
+/** Public struct with the finish state contents */
+typedef struct cmt_rollup_finish {
+    bool accept_previous_request;
+    int next_request_type;
+    uint32_t next_request_payload_length;
+} cmt_rollup_finish_t;
+
+/** Public struct with generic io request/response */
+typedef struct cmt_gio {
+    uint16_t domain;               /**< domain for the gio request */
+    uint32_t id_length;            /**< length of id */
+    void *id;                      /**< id for the request */
+    uint16_t response_code;        /**< response */
+    uint32_t response_data_length; /**< length of response data */
+    void *response_data;           /**< response data */
+} cmt_gio_t;
+
+/** Initialize a @ref cmt_rollup_t state.
+ *
+ * @param [in] me uninitialized state
+ *
+ * @return
+ * |   |                             |
+ * |--:|-----------------------------|
+ * |  0| success                     |
+ * |< 0| failure with a -errno value | */
+int cmt_rollup_init(cmt_rollup_t *me);
+
+/** Finalize a @ref cmt_rollup_t state previously initialized with @ref
+ * cmt_rollup_init
+ *
+ * @param [in] me    initialized state
+ *
+ * @note use of @p me after this call is undefined behavior. */
+void cmt_rollup_fini(cmt_rollup_t *me);
+
+/** Emit a voucher
+ *
+ * Equivalent to the `Voucher(address,uint256,bytes)` solidity call.
+ *
+ * @param [in,out] me             initialized @ref cmt_rollup_t instance
+ * @param [in]     address        destination data
+ * @param [in]     value          value data
+ * @param [in]     data           message contents
+ * @param [out]    index          index of emitted voucher, if successful
+ *
+ * @return
+ * |   |                             |
+ * |--:|-----------------------------|
+ * |  0| success                     |
+ * |< 0| failure with a -errno value | */
+int cmt_rollup_emit_voucher(cmt_rollup_t *me, const cmt_abi_address_t *address, const cmt_abi_u256_t *value, const cmt_abi_bytes_t *data, uint64_t *index);
+
+/** Emit a delegate call voucher
+ *
+ * Equivalent to the `DelegateCallVoucher(address,bytes)` solidity call.
+ *
+ * @param [in,out] me             initialized @ref cmt_rollup_t instance
+ * @param [in]     address        destination data
+ * @param [in]     data           message contents
+ * @param [out]    index          index of emitted voucher, if successful
+ *
+ * @return
+ * |   |                             |
+ * |--:|-----------------------------|
+ * |  0| success                     |
+ * |< 0| failure with a -errno value | */
+int cmt_rollup_emit_delegate_call_voucher(cmt_rollup_t *me, const cmt_abi_address_t *address, const cmt_abi_bytes_t *data, uint64_t *index);
+
+/** Emit a notice
+ *
+ * @param [in,out] me          initialized cmt_rollup_t instance
+ * @param [in]     data        message contents
+ * @param [out]    index       index of emitted notice, if successful
+ *
+ * @return
+ * |   |                             |
+ * |--:|-----------------------------|
+ * |  0| success                     |
+ * |< 0| failure with a -errno value | */
+int cmt_rollup_emit_notice(cmt_rollup_t *me, const cmt_abi_bytes_t *payload, uint64_t *index);
+
+/** Emit a report
+ * @param [in,out] me      initialized cmt_rollup_t instance
+ * @param [in]     n       sizeof @p data in bytes
+ * @param [in]     data    message contents
+ *
+ * @return
+ * |   |                             |
+ * |--:|-----------------------------|
+ * |  0| success                     |
+ * |< 0| failure with a -errno value | */
+int cmt_rollup_emit_report(cmt_rollup_t *me, const cmt_abi_bytes_t *payload);
+
+/** Emit a exception
+ * @param [in,out] me          initialized cmt_rollup_t instance
+ * @param [in]     data_length data length in bytes
+ * @param [in]     data        message contents
+ *
+ * @return
+ * |   |                             |
+ * |--:|-----------------------------|
+ * |  0| success                     |
+ * |< 0| failure with a -errno value | */
+int cmt_rollup_emit_exception(cmt_rollup_t *me, const cmt_abi_bytes_t *payload);
+
+/** Report progress
+ *
+ * @param [in,out] me        initialized cmt_rollup_t instance
+ * @param [in]     progress  progress value to be set
+ *
+ * @return
+ * |   |                             |
+ * |--:|-----------------------------|
+ * |  0| success                     |
+ * |< 0| failure with a -errno value | */
+int cmt_rollup_progress(cmt_rollup_t *me, uint32_t progress);
+
+/** Read advance state
+ *
+ * @param [in,out] me      initialized cmt_rollup_t instance
+ * @param [out]    advance cmt_rollup_advance_t instance (may be uninitialized)
+ *
+ * @return
+ * |   |                             |
+ * |--:|-----------------------------|
+ * |  0| success                     |
+ * |< 0| failure with a -errno value | */
+int cmt_rollup_read_advance_state(cmt_rollup_t *me, cmt_rollup_advance_t *advance);
+
+/** Read inspect state
+ *
+ * @param [in,out] me      initialized cmt_rollup_t instance
+ * @param [out]    inspect cmt_rollup_inspect_t instance (may be uninitialized)
+ *
+ * @return
+ * |   |                             |
+ * |--:|-----------------------------|
+ * |  0| success                     |
+ * |< 0| failure with a -errno value | */
+int cmt_rollup_read_inspect_state(cmt_rollup_t *me, cmt_rollup_inspect_t *inspect);
+
+/** Finish processing of current advance or inspect.
+ * Waits for and returns the next advance or inspect query when available.
+ *
+ * @param [in,out] me      initialized cmt_rollup_t instance
+ * @param [in,out] finish  initialized cmt_rollup_finish_t instance
+ *
+ * @return
+ * |   |                             |
+ * |--:|-----------------------------|
+ * |  0| success                     |
+ * |< 0| failure with a -errno value | */
+int cmt_rollup_finish(cmt_rollup_t *me, cmt_rollup_finish_t *finish);
+
+/** Performs a generic IO request
+ *
+ * @param [in,out] me  initialized cmt_rollup_t instance
+ * @param [in,out] req initialized cmt_gio_t structure
+ *
+ * @return
+ * |   |                             |
+ * |--:|-----------------------------|
+ * |  0| success                     |
+ * |< 0| failure with a -errno value | */
+int cmt_gio_request(cmt_rollup_t *me, cmt_gio_t *req);
+
+/** Retrieve the merkle tree and intermediate state from a file @p path
+ * @param [in,out] me      initialized cmt_rollup_t instance
+ * @param [in]     file    path to file (parent directories must exist)
+ *
+ * @return
+ * |   |                             |
+ * |--:|-----------------------------|
+ * |  0| success                     |
+ * |< 0| failure with a -errno value | */
+int cmt_rollup_load_merkle(cmt_rollup_t *me, const char *path);
+
+/** Store the merkle tree and intermediate state to a file @p path
+ *
+ * @param [in,out] me      initialized cmt_rollup_t instance
+ * @param [in]     file    path to file (parent directories must exist)
+ *
+ * @return
+ * |   |                             |
+ * |--:|-----------------------------|
+ * |  0| success                     |
+ * |< 0| failure with a -errno value | */
+int cmt_rollup_save_merkle(cmt_rollup_t *me, const char *path);
+
+/** Resets the merkle tree to pristine conditions
+ *
+ * @param [in,out] me      initialized cmt_rollup_t instance */
+void cmt_rollup_reset_merkle(cmt_rollup_t *me);
+
+#endif /* CMT_ROLLUP_H */