@@ -0,0 +1,212 @@
2+title = "Custom Roller Tutorial"
7+This tutorial is an outline for how to set up your own L2 roller for Urbit. Some
8+familiarity with how L2 works in general, as well as the role of the roller, is
9+expected. See [Layer 2 Overview](/docs/azimuth/l2/layer2) for a technical
10+overview of L2, [Azimuth Data Flow](/docs/azimuth/flow) to gain an understanding
11+of how Azimuth data handling and processing is done on Urbit, and
12+[Rollers](docs/azimuth/l2/roller) for a short summary of what the different Gall
13+agents involved for rollers are. This tutorial is focused on setting up a roller
14+to work on the main Ethereum network, but only minor changes are needed to
15+utilize the Ropsten Ethereum network. We also explain how to set up a front end
16+(Bridge) from which transactions to be batched by the roller are sent, but use
17+of a front end is not mandatory.
19+Note that this process involves giving the private key of an Ethereum wallet to
20+the ship running the roller so that it may spend ETH to submit transactions. If you
21+do not fully understand what this entails, we recommend against running your own
22+roller on the Ethereum mainnet. See [below](#step2) for more information on
25+Henceforth, by "roller" we are referring to the ship used as the transaction
26+aggregator and batch submitter, `%roller` refers to the Gall agent running on
27+the roller that performs these actions, and "front-end" refers to the optional
28+web GUI most users will use to interact with your roller (probably Bridge).
30+There are three main steps involved with setting up a roller:
31+ - ensuring that the data in `%azimuth` is up to date,
32+ - starting and configuring `%roller`,
33+ - aiming your front-end at the roller
35+### 1. Make sure `%azimuth` state is up to date
36+If you are using an ordinary live ship on the network as the roller, you should
37+already have the latest `%azimuth` state and this step should not be necessary
38+and you may move to step 2.
40+If your roller is a fakezod, you will need to configure `%azimuth` to pull the
41+latest [Azimuth](/docs/azimuth/azimuth-eth) data from Ethereum. The most common
42+way to do this is via an Infura node, but you could instead use e.g. your own
43+Ethereum node. A free tier Infura node ought to be sufficient for most people
44+and is easy to set up using their tutorials.
46+To set up your fakezod to automatically receive Azimuth updates from the Infura
47+node, enter the following commands in dojo: `:azimuth %resub` followed by
48+`:azimuth|watch 'https://MAINNET_INFURA_URL' %default`. Here, the url can be
49+found under the Setting page for the node on infura.io listed under `ENDPOINTS`.
51+If you do not perform this step, you'll later see an error "roller not ready"
52+when the first roller batch is about to be submitted.
54+### 2. Starting and configuring `%roller` {#step2}
55+This step must be performed whether you're using a fakezod or a live ship.
57+First we need to start `%roller` and `%roller-rpc` (the agent used to send
58+commands to `%roller` via HTTP). If you are not making use of a front-end, and
59+instead will be accepting transactions to batch entirely from within Urbit,
60+`%roller-rpc` is not necessary. We assume you will be using Bridge as a
63+To start the agents, enter the following command in dojo: `|rein %base [&
64+%roller] [& %roller-rpc]`. You should see the following response:
67+gall: installing %roller-rpc
69+gall: installing %roller
70+> %received-azimuth-state
73+Note that `%received-azimuth-state` only indicates that `%roller` successfully
74+subscribed to `%azimuth`; it does not indicate that you successfully completed
77+Next we need to configure `%roller`. `%roller` has several parameters that can
78+be tweaked, such as how many transactions it will accept from a given ship in a
79+given time period, how long the time period is, how much gas to use, exceptions
80+to these rules for particular ships, etc. We will cover these in a moment, but
81+first there are two mandatory settings that must be configured: the Ethereum
82+node to submit batches to, and the private key for the wallet that will submit
85+First let's set the Ethereum node to which batches will be submitted, which we
86+will presume is an Infura node. This does not need to be the same node given in
87+step 1, but it is fine for them to be the same (assuming it is configured to
88+accept transactions - some Infura nodes are set up only to make blockchain data
89+available but do not participate in propagating transactions). Enter
90+`:roller|endpoint 'https://MAINNET_INFURA_URL' %mainnet` into dojo.
92+Next we set the private key for the Ethereum wallet from which batches built by
93+`%roller` will be submitted. We *strongly emphasize* that this step has serious
94+security implications. *`%roller` will be able to spend ETH in this wallet.*
95+This is mandatory, of course, as the primary function of `%roller` is to submit
96+batches of transactions to Ethereum, which requires ETH. If you downloaded
97+`%roller` from someone other than Tlon and have not personally audited their
98+code, you are putting the assets in this wallet at risk. Also keep in mind that
99+while Urbit has undergone several security audits, some components such as the
100+runtime have never been audited by a third party. We maintain a list of these
101+audits [here](/audits), as well as an
102+[FAQ](https://urbit.org/faq#how-secure-is-urbit) on the state of security in
103+Urbit. Thus we recommend a fresh wallet generated specifically to be used by
104+`%roller` and to only put the amount of ETH in it that you expect to need in the
105+near future. We also recommend that you only use this address for sending L2
106+batches, since otherwise the nonce will get out of sync. `%roller` can detect
107+this and handle it, but it could cause a delay in batch submission.
109+With that being said, the command to set the private key for the wallet to be
110+utilized by the roller is `:roller|setkey '0x1234567890abcdef'`, where `0x...`
113+The `:roller|endpoint` and `:roller|setkey` commands are the only mandatory
114+commands to set up the roller. At this point, if your roller is live on the
115+network (as opposed to a fakezod) and everything has been performed correctly,
116+it would be possible for others to submit transactions to it manually. All other
117+settings are sensible defaults at time of writing. However, to utilize a
118+front-end, one more command is needed: `|cors-approve 'https://YOUR_FRONTEND'`,
119+where the url is the address of the front end you're using - probably a modified
120+Bridge that you're hosting somewhere which you'll set up in the next step.
121+fakezods can only accept transactions from other ships it can talk to, namely
122+other fake ships running on the same machine, so you will need to set it up to
123+work with a front-end if you want to use it on livenet.
125+We cover the additional settings for `%roller` at the end.
127+### 3. Aiming Bridge at the roller
129+The last step is to set up the web interface by which users can submit
130+transactions to be batched by the roller, which we refer to as the front-end. We
131+presume here that you'll be using [Bridge](https://github.com/urbit/bridge), by
132+which we mean you'll be hosting a custom version of Bridge modified to use the
133+roller you set up above instead of Tlon's roller.
135+First you'll need to make the urbit running `%roller` accessible to the web.
136+This is outside the scope of the tutorial, but we suggest using a tool like
137+`caddy` or `nginx`. You'll want to set up a URL such as
138+`https://myroller.sampel-pal.net` and use the port you'd ordinarily use to
139+access Landscape, probably `80` or `8080`. To be clear, this is the same process
140+you'd use if you set up a custom URL to access your urbit hosted in the cloud.
142+To point Bridge at your roller we [launch
143+Bridge](https://github.com/urbit/bridge/blob/master/DEVELOPMENT.md) with a
144+custom command that modifies an environment variable called
145+`REACT_APP_ROLLER_HOST`:
148+REACT_APP_ROLLER_HOST=https://myroller.sampel-pal.net npm run pilot-mainnet
151+This will launch a server running Bridge that utilizes the mainnet roller you
152+set up at `https://myroller.sampel-pal.net`.
154+### Additional `%roller` commmands
156+`%roller` has a few other settings and commands for managing things like the
157+rate at which transactions are submitted and manually submitting batches. These
158+can be modified using the following generators:
161+ <thead><tr><th>Dojo Command</th><th>Description</th><th>Argument</th></tr></thead>
164+ <td><code>:roller|commit</code></td>
165+ <td>Submits a new L2 batch with all pending transactions.</td>
169+ <td><code>:roller|config</code></td>
170+ <td>General configuration command.</td>
171+ <td><code>$config</code> (see <code>/sur/dice.hoon</code>)</td>
174+ <td><code>:roller|endpoint</code></td>
175+ <td>Set the Infura endpoint.</td>
176+ <td><code>[@t ?(%mainnet %ropsten %local)]</code></td>
179+ <td><code>:roller|frequency</code></td>
180+ <td>Sets the frequency at which batches are submitted.</td>
181+ <td><code>@dr</code></td>
184+ <td><code>:roller|local</code></td>
185+ <td>Configures <code>%roller</code> to listen to a local Ethereum node at port 8545.</td>
189+ <td><code>:roller|quota</code></td>
190+ <td>Modified the number of txs a ship is allowed to send per unit time.</td>
191+ <td><code>@ud</code></td>
194+ <td><code>:roller|ropsten</code></td>
195+ <td>Configure %roller to listen to a preset Ropsten Infura node.</td>
199+ <td><code>:roller|setkey</code></td>
200+ <td>Load a private key into the roller and retrieves its L1 nonce.</td>
201+ <td><code>@t</code></td>
204+ <td><code>:roller|slice</code></td>
205+ <td>Modified the unit of time for each ship's quota.</td>
206+ <td><code>@dr</code></td>