@@ -0,0 +1,177 @@
1++++
2+title = "Custom Roller Tutorial"
3+weight = 11
4+template = "doc.html"
5++++
6+
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.
18+
19+Note that this process involves giving the private key of an Ethereum wallet to
20+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
23+this.
24+
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).
29+
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
34+
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.
39+
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.
45+
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`.
50+
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.
53+
54+### 2. Starting and configuring `%roller` {#step2}
55+This step must be performed whether you're using a fakezod or a live ship.
56+
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
61+front-end.
62+
63+To start the agents, enter the following command in dojo: `|rein %base [&
64+%roller] [& %roller-rpc]`. You should see the following response:
65+
66+```
67+gall: installing %roller-rpc
68+> 'init'
69+gall: installing %roller
70+> %received-azimuth-state
71+```
72+
73+Note that `%received-azimuth-state` only indicates that `%roller` successfully
74+subscribed to `%azimuth`; it does not indicate that you successfully completed
75+step 1.
76+
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
83+the transactions.
84+
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.
91+
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.
106+
107+With that being said, the command to set the private key for the wallet to be
108+utilized by the roller is `:roller|setkey '0x1234567890abcdef'`, where `0x...`
109+is the private key.
110+
111+The `:roller|endpoint` and `:roller|setkey` commands are the only mandatory
112+commands to set up the roller. At this point, if your roller is live on the
113+network (as opposed to a fakezod) and everything has been performed correctly,
114+it would be possible for others to submit transactions to it manually. All other
115+settings are sensible defaults at time of writing. However, to utilize a
116+front-end, one more command is needed: `|cors-approve 'https://YOUR_FRONTEND'`,
117+where the url is the address of the front end you're using - probably a modified
118+Bridge that you're hosting somewhere which you'll set up in the next step.
119+fakezods can only accept transactions from other ships it can talk to, namely
120+other fake ships running on the same machine, so you will need to set it up to
121+work with a front-end if you want to use it on livenet.
122+
123+We cover the additional settings for `%roller` at the end.
124+
125+### 3. Aiming Bridge at the roller
126+
127+The last step is to set up the web interface by which users can submit
128+transactions to be batched by the roller, which we refer to as the front-end. We
129+presume here that you'll be using [Bridge](https://github.com/urbit/bridge), by
130+which we mean you'll be hosting a custom version of Bridge modified to use the
131+roller you set up above instead of Tlon's roller.
132+
133+First you'll need to make the urbit running `%roller` accessible to the web.
134+This is outside the scope of the tutorial, but we suggest using a tool like
135+`caddy` or `nginx`. You'll want to set up a URL such as
136+`https://myroller.sampel-pal.net` and use the port you'd ordinarily use to
137+access Landscape, probably `80` or `8080`. To be clear, this is the same process
138+you'd use if you set up a custom URL to access your urbit hosted in the cloud.
139+
140+To point Bridge at your roller we [launch
141+Bridge](https://github.com/urbit/bridge/blob/master/DEVELOPMENT.md) with a
142+custom command that modifies an environment variable called
143+`REACT_APP_ROLLER_HOST`:
144+
145+```
146+REACT_APP_ROLLER_HOST=https://myroller.sampel-pal.net npm run pilot-mainnet
147+```
148+
149+This will launch a server running Bridge that utilizes the mainnet roller you
150+set up at `https://myroller.sampel-pal.net`.
151+
152+### Additional `%roller` commmands
153+
154+`%roller` has a few other settings and commands for managing things like the
155+rate at which transactions are submitted and manually submitting batches. These
156+can be modified using the following generators:
157+
158+```
159+:roller|commit :: submits a new L2 batch with all pending transactions. No argument.
160+:roller|config :: general configuration command. Takes a $config argument (see /sur/dice.hoon)
161+:roller|endpoint :: set the Infura endpoint. Takes a [@t ?(%mainnet %ropsten
162+%local)] argument.
163+:roller|frequency :: Sets the frequency at which batches are submitted. Takes a
164+@dr argument
165+:roller|local :: Configures %roller to listen to a local Ethereum node at
166+port 8545. No argument.
167+:roller|quota :: Modified the number of txs a ship is allowed to send per unit
168+time. Take a @ud argument.
169+:roller|ropsten :: Configure %roller to listen to a preset Ropsten Infura node.
170+No argument.
171+:roller|setkey :: Load a private key into the roller and retrieves its L1
172+nonce. Takes a @t argument.
173+:roller|slice :: Modified the unit of time for each ship's quota. Take a @dr argument.
174+```
175+
176+
177+