Skip to main content

Back-end API

API used by dApp back-ends (running inside Cartesi Nodes) to interact with the Cartesi Rollups framework.

Introduction

API that the Cartesi Rollup HTTP Server implements. In the box below, there is an example of a dApp backend that uses the Rollup HTTP API. ``` import requests import sys rollup = sys.argv[1] def check_status_code(response): if response.status_code not in range(200, 300): print(f'Error: invalid status code {response.status_code}') sys.exit(1) return response finish = {'status': 'accept'} while True: print('Sending finish') r = check_status_code(requests.post(rollup + '/finish', json=finish)) if r.status_code == 202: print('No pending rollup request, trying again') continue rollup_request = r.json() if rollup_request['request_type'] == 'advance_state': print('Sending voucher') voucher = { 'address': rollup_request['data']['metadata']['msg_sender'], 'payload': rollup_request['data']['payload'] } check_status_code(requests.post(rollup + '/voucher', json=voucher)) print('Sending notice') notice = {'payload': rollup_request['data']['payload']} check_status_code(requests.post(rollup + '/notice', json=notice)) print('Sending report') report = {'payload': rollup_request['data']['payload']} check_status_code(requests.post(rollup + '/report', json=report)) finish['status'] = 'accept' elif rollup_request['request_type'] == 'inspect_state': print('Sending report per inspect request') report = {'payload': rollup_request['data']['payload']} check_status_code(requests.post(rollup + '/report', json=report)) else: print('Throwing rollup exception') exception = {'payload': rollup_request['data']['payload']} requests.post(rollup + '/exception', json=exception) break ```

Finish and get next request

The dApp backend should call this method to start processing rollup requests. The Rollup HTTP Server returns the next rollup request in the response body. The possible values for the request_type field are 'advance_state' and 'inspect_state'. The data field contains the rollup request input data. For advance-state requests, the input data contains the advance-state metadata and the payload. For inspect-state requests, the input data contains only the payload. After processing an rollup request, the dApp-backend should call again the finish method. For advance-state requests, depending on the result of the request processing, it should fill the status field of the request body with 'accept' or 'reject'. The Rollup HTTP Server ignores the content of the status field for the first finish request and after an inspect-state request. If the advance-state request is rejected, the vouchers and notices are discarded. In contrast, reports are not discarded in case of reject. When running inside a Cartesi Machine, the Cartesi Server Manager reverts the entire state of the machine to what it was before receiving the request. During a finish call, the next rollup request might not be immediately available. When the dApp backend and the Rollup HTTP Server are running inside a Cartesi Machine, the Cartesi Server Manager pauses the whole machine execution until the next request is ready. When running in host mode, the Rollup HTTP Server returns the status code 202 after 10 seconds to avoid the connection timing out. When the Rollup HTTP Server returns 202, the dApp backend should retry the call to finish passing the same arguments as before.

© 2024 Cartesi Foundation Ltd. All rights reserved.

The Cartesi Project is commissioned by the Cartesi Foundation.

We use cookies to ensure that we give you the best experience on our website. By using the website, you agree to the use of cookies.