git.iko.soy/bridge
on master help sign in
bridge/DEVELOPMENT.md
218 lines 7.7 kB history raw
1# Development notes
3## Install / Build
5Clone the repo, and use a simple `npm install`. You can then use a `npm run build` to create an optimised static build (serve it with e.g. [serve](http://npmjs.com/package/serve), or with python as described above).
7## General notes
9For development, use `npm run pilot` to get going after a `npm install`. This
10will boot up a [Ganache](https://github.com/trufflesuite/ganache-cli) node in the background, deploy the Azimuth contracts to
11it, and fire up a local webserver. Bridge will be served on `localhost:3000`.
13Note that one of our dependencies itself depends on a library called
14`handle-thing` which breaks under the Ledger support requirements (see below)
15on node 11.1.0, so make sure you're using some other node version.
17You can use [nvm](https://github.com/creationix/nvm), for example, and do:
19```
20$ nvm install 14.17.0
21$ nvm use v14.17.0
22```
24before running `npm run pilot`.
26## Useful accounts
28The ecliptic owner is the only account that's able to create galaxies, so
29it's a good place to get started. On the testnet, it's the address:
31```
320x6DEfFb0caFDB11D175F123F6891AA64F01c24F7d
33```
35You can authenticate as it using the following mnemonic:
37```
38benefit crew supreme gesture quantum web media hazard theory mercy wing kitten
39```
41Under that mnemonic, Ganache will also auto-populate the following accounts
42with 100 ETH:
44```
450x6deffb0cafdb11d175f123f6891aa64f01c24f7d
460xd53208cf45fc9bd7938b200bff8814a26146688f
470x7b2a2d51e4d8fac602e20a5f6907ff9fbd88e1fd
480xf48062ae8bafd6ef19cd6cb89db93a0d0ca6ce26
490xf84a77aeb351c49dfa87e805a659d2daddff7606
500x167e357cf8b845370d0d408f9b389b66185b7b5b
510xcbecf3abc9878f07afc851aead2d8f1c436cc71d
520x0afc0c3f4eeea500871f464ca71eef5e54a9af36
530x6d654ef2489674d21aed428e8a4ad8ca4820f125
540x218f6f87683db546ad47a5dc8b480e5a9b694866
55```
57To play around with any of these, authenticate using the same mnemonic, but
58use a custom HD path of `m/44'/60'/0'/0/1`, `m/44'/60'/0'/0/2`, and so on.
60## Initial development state
62You can also tweak a couple of things to change your development state
63somewhat (say, for example, you want to start on the points list screen, instead
64of having to re-authenticate whenever you make a change or refresh the page):
66- The `.env.development` file contains environment variables that you can
67 provide to the application when it's running in development. You can access
68 them via `import.meta.env.VITE_<whatever>`.
70- Set `VITE_STUB_LOCAL='true'` in `.env.development` to enabled stubbing of
71 certain methods throughout the app.
73- The top of the Bridge component in `src/Bridge.js` can be tweaked for setting
74 your initial state. You can provide a specific wallet,
75 network type, and so on.
77- `npm run pilot` will check the `WITH_TEST_STATE` environment variable to setup
78 the initial chain state. Possible values are `STAR_RELEASE` or `INVITES`.
79 The state setup can be found in `migrations/1_migration.js`
81## HTTPS
83For development, Bridge will not run unless you access localhost via HTTPS. To do this, you will want to set up a self-signed cert using `mkcert`:
851. Install `mkcert`:
86```
87# on MacOS using homebrew
88brew install mkcert
90# on Linux using apt # TODO Confirm functionality
91sudo apt install libnss3-tools
92wget -O mkcert https://github.com/FiloSottile/mkcert/releases/latest/download/mkcert-v*-linux-amd64
93chmod +x mkcert
94sudo mv mkcert /usr/local/bin/
95```
972. Create certificate authority:
98```
99# install local cert authority
100mkcert -install
101```
1033. Generate localhost Cert:
104```
105# Navigate to your bridge project directory
106cd /path/to/urbit/bridge
108# Generate certificate for localhost
109mkcert localhost 127.0.0.1 ::1
110```
112This creates two files:
113- `localhost+2.pem` (certificate)
114- `localhost+2-key.pem` (private key)
117Note: as of 3.3.0, Bridge is deprecating explicit support for Firefox. Privacy focused users are recommended to use Brave Browser.
119## WalletConnect
121To get WalletConnect working you need to set the `VITE_WALLET_CONNECT_PROJECT_ID`
122environment variable with a project id that you can get at https://cloud.walletconnect.com/sign-in
124## Testing
126Automated tests for critical user journeys are coming Soon™️. Until then, here are several manual test cases to consider when making changes. It's worth noting that what to test depends on what the changes are. These test cases have limited utility when you are making a small change on a single screen; however, they are certainly a good idea when touching critical pieces such as transaction sending or secrets derivation.
128### Mnemonic Login
130"As a user, I can log into Bridge using a BIP39 mnemonic phrase"
1321. Click the 'Mnemonic, Metamask, Hardware Wallet ...' Button, then click 'Mnemonic (BIP 39)'
1332. Paste the mnemonic above (in 'Useful Accounts') into the text area, then click 'Login'
1343. Confirm that you are able to view the Points list view. Since no points have been created yet, you should see the following message:
135> No points to display. This wallet is not the owner or proxy for any points.
137### Planet Creation
139"As a user, I can create a new planet"
1411. Once a star has been created, click it in the points list
1422. Click "Issue Point", enter one of the suggested planet names, and sign and send the transaction
1433. Log out and back into Bridge, confirm that the newly created planet is rendered in the points list
145### Invite Issuance
147"As a user, I can create a new invite"
149First, in `Bridge.js`, set the `INITIAL_NETWORK_TYPE` to Goerli:
150```js
151const INITIAL_NETWORK_TYPE = NETWORK_TYPES.GOERLI;
152```
154Then, in `tank.js`, set the port to `3011`:
155```js
156const baseUrl = 'https://gas-tank.urbit.org:3011';
157```
1591. Ask one of the Collaborators of this project for an Invite code :)
161(If you're generating a code, don't forget to set `inviteMail.js` port to `:3012` for testnet)
163### Invite Acceptance
165"As a new Urbit user, I can set up a new ID with an activation code"
1671. On the Bridge landing page, click the small "Activate" link
1682. Paste the Invite code from the previous test case, and click "Go"
1693. Download the Passport file, then use the enclosed Master Ticket and ID to login to Bridge again
171### Known Issues
173When testing the invite acceptance and login flow on Goerli, some of the Azimuth API calls will fail (e.g., `getConditional`).
175## Releases
177To generate a release `bridge-$VERSION.zip` file, use a simple `npm run release`.
179This will pack the build directory together with the README, `bridge-https.py`
180script, and also generate a set of checksums for the build directory. You can
181verify the checksums on e.g. MacOS via `shasum -c checksums.txt`.
183## L2 Local Environment
185To work with the L2 aggregator locally, set up the local environment like so:
187```sh
188# Start Bridge with local blockchain preloaded with L1 and L2 points, all owned by the address 0x6DEfFb0caFDB11D175F123F6891AA64F01c24F7d
190npm run pilot-l2
191```
193Start a local fake ship from the master branch in the [urbit repo](https://github.com/urbit/urbit)
195```sh
196/path/to/urbit -F zod -B ./bin/solid.pill -A ./pkg/arvo -c zod --http-port 8080
197```
199```dojo
200:: Run these in the dojo:
201::
202> |mount /=base=
203> |nuke %azimuth
204> |rein %base [%.y %azimuth]
205> :azimuth|watch 'http://0.0.0.0:8545' %local
206> :azimuth %resub
207> :azimuth &azimuth-poke [%kick ~]
208> |rein %base [& %roller] [& %roller-rpc] [& %azimuth-rpc]
209> :roller|local
210> :roller|setkey '58d62eb79797502bc0f66cd3e7a49d00287bff53a2734b799ef09cb746340ed0'
211> :roller|quota 9.999
212:: If you run into issues, also add 'https://localhost:3000' the the eyre CORS approvals
213> |eyre/cors/approve 'https://127.0.0.1:3000'
214::
215:: Once L2 txs have been sent via Bridge, this will manually commit and batch them, avoiding waiting for the timer
216::
217> :roller|commit
218```