Updating README.md for macOS (#348)

* Updating README.md * Add docs for setting up a local chain
anoma · Jul 31, 2023 · 44002e4 · 44002e4
1 parent 8b455e5
commit 44002e4
Show file tree

Hide file tree

Showing 4 changed files with 132 additions and 146 deletions.
diff --git a/README.md b/README.md
@@ -4,89 +4,83 @@
     <img style="width: 300px;" src="banner-image.png" />
 </div>
 
-There is a seperate more details specifications documentation under [/specs](https://github.com/anoma/namada-interface/blob/main/specs)
+See our `specs` for more detailed documentation in [/specs](https://github.com/anoma/namada-interface/blob/main/specs)
+
+- [Installation](#installation)
+  - [Ubuntu Linux](#ubuntu)
+  - [macOS](#macos)
+  - [Apple Silicon](#apple-silicon)
+- [Usage](#usage)
+  - [Local Chain](#local-chain)
+  - [Extension](#extension)
+  - [Interface](#interface)
+  - [Testing](#testing)
+    - [Unit](#unit)
+    - [e2e](#e2e)
+
+## Installation
+
+Before using apps in this repo, we first need to install all dependencies.
+
+### Ubuntu
 
-<h2> Run namada-interface </h2>
+_NOTE_ These instructions may work with other Ubuntu-based systems, but are only confirmed to work in Ubuntu.
 
 ```bash
-# go to the directory of namada-interface web app
-cd apps/namada-interface
+# Install rustup
+curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
 
-# other OS
-yarn wasm:build
+# Add WASM target
+rustup target add wasm32-unknown-unknown
 
-# on ARM based mac do this instead:
-# xcode-select --install
-# brew install llvm
-# CC=/opt/homebrew/opt/llvm/bin/clang AR=/opt/homebrew/opt/llvm/bin/llvm-ar yarn wasm:build
+# Install clang
+sudo apt-get install -y clang
 
-yarn
-yarn start
-```
+# Install pkg-config
+sudo apt-get install -y pkg-config
 
-for solving possible issue see [Troubleshooting](#troubleshooting)
+# Install openssl development packages
+sudo apt-get install -y libssl-dev
 
-- [Introduction](#introduction)
-  - [Usage](#usage)
-  - [Project Structure](#project-structure)
-    - [Utils / Theme](#utils--theme)
-      - [Colors](#colors)
-      - [Example](#example)
-      - [Exceptions](#exceptions)
-  - [Testing](#testing)
-    - [Unit](#unit)
-    - [e2e](#e2e)
+# Install protoc
+sudo apt-get install -y protobuf-compiler
 
-## Introduction
+# Install wasm-pack
+ curl https://rustwasm.github.io/wasm-pack/installer/init.sh -sSf | sh
 
-This is the `namada-interface` monorepo. Within it, you will find the code for the web wallet implementation. it contains the following packages:
+# Install yarn and JS dependencies
+npm install -g yarn
 
-```bash
-namada-interface/
-└── apps/
-    ├── namada-interface/   # Main wallet React App
-    ├── extension/          # Browser Extension React App
-└── packages/
-    ├── crypto/          # Crypto functions related to namada extension and interface
-    ├── integrations/    # Third-party wallet integrations
-    ├── masp-web/        # utilities for performing MASP actions
-    ├── rpc/             # Library for handling HTTP and WebSocket RPC calls
-    ├── seed-management/ # Seed management library
-    ├── session/         # Session management library
-    ├── shared/          # Package for interfacing with `namada/shared`
-    ├── tx/              # Library for interfacing with Namada transactions
-    ├── utils/           # Shared utilities
-    ├── wallet/          # Library for deriving keys
-    └── wasm/            # Legacy wasm library
-```
+# within namada-interface/ base folder:
+yarn
 
-### Usage
+# Install web-ext
+yarn global add web-ext
+```
 
-Before using apps in this repo, we first need to install all
-dependencies. Note that these commands are for Ubuntu and will vary on
-other systems:
+### macOS
 
 ```bash
+# Install xcode
+xcode-select --install
+
 # Install rustup
 curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
 
 # Add WASM target
 rustup target add wasm32-unknown-unknown
 
 # Install clang
-sudo apt-get install -y clang
+brew install clang
 
 # Install pkg-config
-sudo apt-get install -y pkg-config
+brew install pkg-config
 
 # Install openssl development packages
-sudo apt-get install -y libssl-dev
-
-# Install wasm-bindgen-cli
-cargo install wasm-bindgen-cli
+brew install libssl-dev
 
 # Install protoc
-sudo apt-get install -y protobuf-compiler
+brew install protobuf
 
 # Install wasm-pack
  curl https://rustwasm.github.io/wasm-pack/installer/init.sh -sSf | sh
@@ -101,14 +95,19 @@ yarn
 yarn global add web-ext
 ```
 
-#### macOS on Intel and Apple Silicon
+Finally, update your shell environment (e.g., in `~/.zshrc`) to set the following variables:
+
+```
+export CC=/usr/local/opt/llvm/bin/clang
+AR=/usr/local/opt/llvm/bin/llvm-ar
+```
+
+#### Apple Silicon
 
 On macOS, when using Apple Silicon architecture, in order to compile some packages for our wasm dependencies, you will need to install
 the following:
 
 ```
-xcode-select --install
-
 # Mac M1/M2 only - install brew's version of llvm
 brew install llvm
 ```
@@ -121,117 +120,113 @@ export LDFLAGS="-L/opt/homebrew/opt/llvm/lib"
 export CPPFLAGS="-I/opt/homebrew/opt/llvm/include"
 export CC=/opt/homebrew/opt/llvm/bin/clang
 export AR=/opt/homebrew/opt/llvm/bin/llvm-ar
-
-# Mac Intel only
-export CC=/usr/local/opt/llvm/bin/clang
-AR=/usr/local/opt/llvm/bin/llvm-ar
 ```
 
-At the root-level, we can issue commands for all packages in the monorepo. Following is an example:
+## Usage
 
-```bash
-# Execute all tests within monorepo
-yarn test
+### Local chain
 
-# Lint all packages
-yarn lint
+Before you start the extension and interface, you will need at least a chain ID and an RPC URL. This can either be a local chain or an
+existing network. If you know the chain ID and URL, you can skip the following and simply enter these values in the `apps/namada-interface/.env`
+file (to see an example of the values you can set, see [.env.sample](./apps/namada-interface/.env.sample).)
 
-# Fix linting on all packages
-yarn lint:fix
-```
+To build and run the chain locally, you will need to clone <http://github.com/anoma/namada>.
 
-There are also app-specific instructions in the [namada-interface README](apps/namada-interface/README.md) and the [extension README](apps/extension/README.md).
+1. In `namada/`, first run `make build`
+2. Then initialize a local chain with:
 
-### Project Structure
+   ```bash
+   namadac utils init-network --genesis-path genesis/e2e-tests-single-node.toml --wasm-checksums-path wasm/checksums.json --chain-prefix local --unsafe-dont-encrypt --localhost --allow-duplicate-ip
+   ```
 
-The app is split in 4 major parts: `App`, `Components`, `State`, `Utils`.
+   Make note of the chain ID from this output! This will be used below where `{CHAIN_ID}` is denoted (replace these instances
+   with the actual chain ID). 3. To transfer funds from faucet via the CLI, you will need to create a wallet:
 
-- **App** - This contains a flat structure of the views of the wallet. These can be then composed in desired hierarchy and flows with routing and navigation. One of the main purposes of the components in `App` is to create layouts and map the state to the visual components.
-- **Components** - These are the visual and generic components of the app. Ideally anything that the user is seeing is composed of these components.
-- **State** - This lives under `slices` directory and is based on Redux and Redux Thunk using [Redux Toolkit](https://redux-toolkit.js.org). This is where the business logic of the app lives. This is where all the calls to libraries and to the network are initiated from.
-- **utils** - Anything that did not go to one of the previous 3, should be here.
-  - **theme** - The app is using styled-components for styling the components. There us a system in-place that maps the designs to the styles in the app. This is explanied more in detail below.
+   ```bash
+   namadaw key gen --alias my-key
+   ```
 
-#### Utils / Theme
+3. Before running the chain, you will need to change one configuration file:
+   - On Linux: Edit `~/.local/share/namada/{CHAIN_ID}/setup/validator-0/.namada/{CHAIN_ID}/config.toml`
+   - On macOS: Edit `~/Library/Application\ Support/Namada/{CHAIN_ID}/setup/validator-0/.namada/{CHAIN_ID}/config.toml`
+4. In `config.toml`, change the line `cors_allowed_origins = []` to `cors_allowed_origins = ["*"]`, then save and close.
+5. You can now start the local chain
 
-The styles are initially defined in Figma [here](https://www.figma.com/file/NFyHbLZXBSl3aUsMxtffvV/Namada-Wallet?node-id=3%3A12). The style consist of:
+   - On Linux:
 
-- colors
-- spaces
-- border radius
-- type information
-  - font family
-  - sizes
-  - weights
-  - colors
+   ```bash
+   namadan --chain-id {CHAIN_ID} --base-dir ~/.local/share/Namada/{CHAIN_ID}/setup/validator-0/.namada ledger run
+   ```
 
-All this information is typed in the app under `apps/namada-interface/src/utils/theme/theme.ts`. The 2 most important types are `PrimitiveColors` which defines the colors. And `DesignConfiguration` which collects all design tokens together. Now some of the styles are different between light and dark modes. We alrways define 2 `PrimitiveColors`, one for light and one for dark. The getter function returns the correct based on which mode the user has selected.
+   - On macOS:
 
-##### Colors
+   ```bash
+   namadan --chain-id {CHAIN_ID} --base-dir ~/Library/Application\ Support/Namada/{CHAIN_ID}/setup/validator-0/.namada ledger run
+   ```
 
-Under colors we have 6 main color groups:
+6. Edit the following value in `namada-interface/apps/namada-interface/.env` (remember to replace `{CHAIN_ID}`
+   with the actual chain ID from above):
 
-- **primary** - main brand specific
-- **secondary** - secondary brand specific
-- **tertiary** - tertiary brand specific
-- **utility1** - mostly backgrounds and panels
-- **utility2** - mostly foregrounds and texts
-- **utility3** - generic utils such as warning, error, ...
+   ```bash
+   REACT_APP_NAMADA_CHAIN_ID={CHAIN_ID}
+   REACT_APP_NAMADA_URL=http://127.0.0.1:27657/
+   ```
 
-https://www.figma.com/file/aiWZpaXjPLW6fDjE7dpFaU/Projects-2021?node-id=9102%3A8806
+### Extension
 
-##### Example
+Within `apps/extension/`, we may issue the following commands:
 
-Then in styled components we can do:
+```bash
+# Build wasm dependencies
+yarn build:wasm
+
+# Build wasm dependencies with debugging enabled
+yarn build:wasm:dev
+
+# Run development extension for Chrome
+yarn start:chrome
+
+# Run development extension for Firefox
+yarn start:firefox
+
+# Build Chrome extension (production version)
+yarn build:chrome
 
-```ts
-export const AccountCreationContainer = styled.div`
-  background-color: ${(props) => props.theme.colors.primary.main80};
-`;
+# Build Firefox extension (production version)
+yarn build:firefox
 ```
 
-##### Exceptions
-
-Sometimes we cannot use same color (such as `colors.primary.main80`) for both the dark and light modes. Such as the logo. In these cases we define a getter in styles component (or React) files to facilitate this difference. This is pretty verbose, yet very maintainable. This could be all central, but i feel it is better when close to the consumer.
-
-```ts
-// Button.components.ts
-import { DesignConfiguration } from "utils/theme";
-
-enum ComponentColor {
-  ButtonBackground,
-  ContainedButtonLabelColor,
-}
-
-const getColor = (
-  color: ComponentColor,
-  theme: DesignConfiguration
-): string => {
-  const isDark = theme.themeConfigurations.isLightMode;
-  switch (color) {
-    case ComponentColor.ButtonBackground:
-      return isDark ? theme.colors.primary.main : theme.colors.secondary.main;
-    case ComponentColor.ContainedButtonLabelColor:
-      return isDark ? theme.colors.utility3.black : theme.colors.utility3.black;
-  }
-};
-
-// then we use it like this
-export const ContainedButton = styled.div`
-  color: ${(props) => props.theme.colors.primary.main};
-  background-color: ${(props) =>
-    getColor(ComponentColor.ButtonBackground, props.theme)};
-`;
+### Interface
+
+Within `apps/namada-interface/`, we may issue the following commands:
+
+```bash
+# Run development interface, hosted at http://localhost:3000
+yarn dev:local
+
+# Build production version
+yarn build
 ```
 
+There are also app-specific instructions in the [namada-interface README](apps/namada-interface/README.md) and the [extension README](apps/extension/README.md).
+
 ### Testing
 
 #### Unit
 
+At the root-level, we can issue commands for all packages in the monorepo. Following is an example:
+
 ```bash
+# Execute all tests within monorepo
 # Running this from the root project directory will run unit tests
 # for all packages where a test script is defined
 yarn test
+
+# Lint all packages
+yarn lint
+
+# Fix linting on all packages
+yarn lint:fix
 ```
 
 #### e2e

diff --git a/apps/extension/README.md b/apps/extension/README.md
@@ -5,9 +5,6 @@ This is the Namada Browser Extension project.
 ## Usage
 
 ```bash
-# First, install wasm-bindgen-cli (for related dependencies) if you haven't already:
-cargo install -f wasm-bindgen-cli
-
 # Install web-ext globally (this bundles Firefox extensions into a `.zip` file):
 yarn global add web-ext
 

diff --git a/packages/crypto/README.md b/packages/crypto/README.md
@@ -15,9 +15,6 @@ The Rust source code lives in `lib/`, and currently provides the following crate
 From the base `crypto` directory, we can build to wasm targets using the following:
 
 ```bash
-# Install wasm-bindgen-cli
-cargo install -f wasm-bindgen-cli
-
 # Build to web wasm target
 yarn wasm:build
 

diff --git a/packages/shared/README.md b/packages/shared/README.md
@@ -5,9 +5,6 @@ Namada shared library functionality, providing wasm-compability for features in
 ## Usage
 
 ```bash
-# Install wasm-bindgen-cli
-cargo install -f wasm-bindgen-cli
-
 # Build to a wasm target (for web)
 yarn wasm:build