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 = { 'destination': 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 ``` In production mode, if the dApp exits the Rollups initialization script will register a Rollup Exception. See [/exception](#api-Default-registerException). In host mode, the Cartesi Rollups infrastructure is not able to detect that the dApp exited. It is up to the dApp developer to re-launch the dApp.
Add a new notice
The dApp backend can call this method to add a new notice when processing the advance-state request. A notice describes any changes to the internal state of the dApp that may be relevant to the blockchain. Between calls to the finish method, the notice method can be called up to 32k times. The returned value is the index of the notice for the current advance request. In other words, the index counting restarts at every request.
Add a new report
The dApp can call this method to add a new report for the given rollup request. A report can be a diagnostic or a log; reports are not discarded when a request is rejected. Between calls to the finish method, the report method can be called any number of times.
Add a new voucher
The dApp backend can call this method to add a new voucher when processing an advance-state request. Vouchers are collateral effects actionable in the blockchain. Between calls to the finish method, the voucher method can be called up to 32k times. The returned value is the index of the voucher for the current advance-state request. In other words, the index counting restarts at every request.
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 a rollup request, the dApp back-end 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 rejection. 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.
Register an exception
The dApp should call this method when it cannot proceed with the request processing after an exception happens. This method should be the last method ever called by the dApp backend while processing a request. When running in production mode, the Cartesi Server Manager pauses the Cartesi Machine and reverts the entire state of the machine to what it was before receiving the request. No HTTP status code will be sent or received. When running in host mode, the Rollup HTTP Server returns the status code 200. In both cases, the input will be skipped with the reason EXCEPTION and the exception message will be forwarded.