Skip to content

Commit f22b1d5

Browse files
truemillertruemiller
committed
docs: updated docs
1 parent bcf85dc commit f22b1d5

File tree

5 files changed

+343
-202
lines changed

5 files changed

+343
-202
lines changed

‎README.md

+26-202
Original file line numberDiff line numberDiff line change
@@ -2,223 +2,47 @@
22
<b>Pearl</b>
33
</h1>
44

5-
Pearl is an application used to run autonomous agents powered by the OLAS Network.
6-
7-
## Technologies Used
8-
9-
- Electron
10-
- NodeJS (20.11 LTS)
11-
- AntD (^5)
12-
- NextJS (^14)
13-
- Javascript / TypeScript
14-
- Python (3.10)
15-
- Poetry (^1.7.1)
5+
A cross-platform desktop application used to run autonomous agents powered by the OLAS Network.
166

177
## Getting Started
188

19-
### Installing system dependencies
20-
21-
The following installation steps assume you have the following on each OS:
22-
23-
- Linux: a debian based operating system such as Ubuntu with `apt` to install packages.
24-
- MacOS: [Homebrew](https://brew.sh/)
25-
26-
<details><summary><h4>NodeJS</summary></h4>
27-
28-
NodeJS is best installed and managed through NVM. It allows you to install and select specific versions of NodeJS. Pearl has been built using version 20 LTS.
29-
30-
<h5>Linux</h5>
31-
32-
```bash
33-
sudo apt install curl
34-
curl https://raw.githubusercontent.com/creationix/nvm/master/install.sh | bash
35-
source ~/.bashrc
36-
nvm install --lts
37-
nvm use --lts
38-
```
39-
40-
<h5>MacOS</h5>
41-
42-
```bash
43-
brew install nvm
44-
```
45-
46-
Set up NVM for console usage. Dependant on the shell, you should edit the config file to contain the following code.
47-
If you're using Bash or Zsh, you might add them to your `~/.bash_profile`, `~/.bashrc`, or `~/.zshrc` file:
48-
49-
```bash
50-
export NVM_DIR="$HOME/.nvm"
51-
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh" # This loads nvm
52-
[ -s "$NVM_DIR/bash_completion" ] && \. "$NVM_DIR/bash_completion" # This loads nvm bash_completion
53-
```
54-
55-
Close and reopen Terminal, or run `source ~/.bash_profile`, `source ~/.zshrc`, or `source ~/.bashrc` to reload the shell configuration.
56-
57-
Verify your installation by running `nvm --version`. Then run:
58-
59-
```bash
60-
nvm install --lts
61-
nvm use --lts
62-
```
63-
64-
</details>
65-
66-
<details><summary><h4>Yarn</h4></summary>
67-
68-
Yarn is the package manager used for dependency management of the Electron app and NextJS frontend.
69-
70-
```bash
71-
npm install --global yarn
72-
```
73-
</details>
74-
75-
<details><summary><h4>Python</h4></summary>
76-
77-
<h5>Linux</h5>
78-
79-
```bash
80-
sudo apt install python3
81-
```
82-
83-
<h5>MacOS</h5>
84-
85-
```bash
86-
brew install python
87-
```
88-
89-
</details>
90-
91-
<details><summary><h4>PIPX</h4></summary>
92-
93-
<h5>Linux</h5>
94-
95-
```bash
96-
sudo apt install pipx
97-
```
98-
99-
<h5>MacOS</h5>
100-
101-
```bash
102-
brew install pipx
103-
```
104-
105-
</details>
106-
107-
<details><summary><h4>Poetry</h4></summary>
108-
109-
Poetry is used on the backend to install and manage dependencies, and create a virtual environment for the backend API.
110-
111-
```bash
112-
pipx install poetry
113-
```
114-
115-
If promoted to run `pipx ensurepath`, run it.
116-
117-
</details>
118-
119-
<h3>Setting up your .env file</h3>
120-
121-
Create an `.env` file in the root directory, or rename `.env.example` to `.env`.
122-
Then set the following environment variables.
123-
124-
<details><summary><h4>NODE_ENV</h4></summary>
125-
126-
For development usage, set `NODE_ENV=development`.
127-
For production usage, set `NODE_ENV=production`.
128-
129-
</details>
130-
131-
<details><summary><h4>FORK_URL</h4></summary>
132-
133-
**This variable is required for both development and production.**
134-
**Must be a Gnosis Mainnet RPC URL.**
135-
136-
- In `development` this RPC url is only used if/when forking mainnet with Hardhat (covered later). This process allows you to test without losing funds.
137-
- In `production` this RPC URL is used as the main RPC for Pearl.
138-
139-
You can get a Gnosis RPC from [Nodies](https://www.nodies.app/).
140-
141-
Once you have a Gnosis Mainnet RPC URL, set `FORK_URL=YOUR_RPC_URL_HERE` in your .env file.
142-
143-
Note: this must be an external RPC. If you decide to use Hardhat for testing on a mainnet fork, do _not_ set your Hardhat Node URL here.
144-
</details>
145-
146-
<details><summary><h4>DEV_RPC</h4></summary>
147-
148-
This environment variable is only used when `NODE_ENV=development` is set.
149-
150-
In `development` mode, it is used throughout Pearl as the main RPC.
151-
152-
If you're using Hardhat, you can set `DEV_RPC=http://localhost:8545`.
153-
Or, you can use another, external RPC URL that wish to test on, ensuring that the chain ID is 100 (Gnosis Mainnet's chain ID).
154-
155-
</details>
156-
157-
<h3>Installing project dependencies</h3>
158-
159-
Run the following command to install all project dependencies.
160-
161-
```bash
162-
yarn install-deps
163-
```
164-
165-
<h3>Running the application</h3>
166-
167-
Provided your system dependencies are installed, environment variables are set, and your RPC is running.
168-
169-
You can start Pearl by running the following command in the root directory:
170-
171-
```bash
172-
yarn dev
173-
```
174-
175-
This will run Electron, which launches the NextJS frontend and the Python backend as child processes.
176-
177-
<h3>Chain forking (for development)</h3>
178-
179-
In the interest of protecting your funds during development, you can run a forked version of Gnosis Mainnet.
180-
181-
There are two recommended options, choose one:
182-
183-
<details><summary><h4>Tenderly (preferred)</h4></summary>
9+
### For Users
18410

185-
[Tenderly](https://tenderly.co/) is a service with a plethora of useful blockchain development tools. The tool required here gives you the ability to **fork networks**.
11+
#### Downloading the latest release
18612

187-
You can also monitor all transactions, and fund your accounts with any token that you please.
13+
**Note:** The release pages also contain Source Code `.zip` files and `dev-` prefixed builds. These are not intended for general use. Ignore them unless you're a developer!
18814

189-
1. Signup to [Tenderly](https://tenderly.co/), and select the plan you desire. **The Free plan should suffice for most users**.
190-
2. Go to *Forks* under the *Development* tab -- in the left sidebar of your dashboard.
191-
3. Click *Create Fork*, select "Gnosis Chain" as the network, and use Chain ID `100`.
192-
4. Copy the RPC url into the appropriate .env variables in your repository. (Recommended to set both `FORK_URL` & `DEV_RPC` to this RPC url during development).
193-
5. Click the *Fund Accounts* button to fund your accounts with XDAI (native token) and [OLAS](https://gnosisscan.io/token/0xce11e14225575945b8e6dc0d4f2dd4c570f79d9f).
15+
- Go to the [Releases](https://github.com/valory-xyz/olas-operate-app/releases) page.
16+
- Download the latest release for your operating system.
17+
- If you're on Windows, download the `.exe` file.
18+
- If you're on MacOS, download the `.dmg` file.
19+
- Both Intel x64 and Apple Silicon ARM64 builds are available.
20+
- Install the application by running the downloaded file.
19421

195-
</details>
22+
### For Developers
19623

197-
<details><summary><h4>Hardhat</h4></summary>
198-
Note: using Hardhat will result in the loss of chain state once your Hardhat node is turned off.
24+
#### Setting up your development environment
19925

200-
Run the following command in the root of your project folder to start your Hardhat node:
26+
- Ubuntu Setup Guide: [docs/dev/ubuntu-setup.md](docs/dev/ubuntu-setup.md)
27+
- MacOS Setup Guide: [docs/dev/macos-setup.md](docs/dev/macos-setup.md)
28+
- Windows Setup Guide: [docs/dev/windows-setup.md](docs/dev/windows-setup.md)
20129

202-
```bash
203-
npx hardhat node
204-
```
30+
#### Setting up a development RPC endpoint
20531

206-
**Once Hardhat is running, you will be able to use `http://localhost:8545` as your development RPC.**
32+
- RPC Setup Guide: [docs/dev/rpcs.md](docs/dev/rpcs.md)
20733

208-
<h5>Funding your addresses with Hardhat</h5>
34+
## Project Dependencies
20935

210-
There are scripts to fund addresses during testing/development:
36+
There are three parts to the project: the Electron app (CommonJS), the NextJS frontend (TypeScript), and the Python backend/middleware.
21137

212-
- XDAI funding:
38+
- Electron dependencies: [package.json](package.json)
39+
- Frontend dependencies: [frontend/package.json](package.json)
40+
- Backend dependencies: [backend/pyproject.toml](backend/pyproject.toml)
21341

214-
```bash
215-
poetry run python scripts/fund.py 0xYOURADDRESS
216-
```
42+
## License
21743

218-
- OLAS funding:
44+
- [Apache 2.0](LICENSE)
21945

220-
```bash
221-
poetry run python scripts/transfer_olas.py PATH_TO_KEY_CONTAINING_OLAS ADDRESS_TO_TRANSFER AMOUNT
222-
```
46+
## Security
22347

224-
</details>
48+
- [Security Policy](SECURITY.md)

‎docs/dev/macos-setup.md

+97
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,97 @@
1+
# Setting up Pearl for development on MacOS
2+
3+
### System dependencies
4+
5+
## 1. Brew
6+
7+
Brew is a package manager for MacOS, allowing you to install packages from the command line.
8+
9+
```bash
10+
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
11+
```
12+
13+
## 2. Node Version Manager (NVM)
14+
15+
NVM is a version manager for Node.js, allowing you to switch between different versions of Node.js.
16+
17+
```bash
18+
brew install nvm
19+
```
20+
21+
Set up NVM for console usage. Dependant on the shell, you should edit the config file to contain the following code.
22+
23+
If you're using Bash or Zsh, you might add them to your `~/.bash_profile`, `~/.bashrc`, or `~/.zshrc` file:
24+
25+
```bash
26+
export NVM_DIR="$HOME/.nvm"
27+
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh" # This loads nvm
28+
[ -s "$NVM_DIR/bash_completion" ] && \. "$NVM_DIR/bash_completion" # This loads nvm bash_completion
29+
```
30+
31+
Close and reopen Terminal, or run `source ~/.bash_profile`, `source ~/.zshrc`, or `source ~/.bashrc` to reload the shell configuration.
32+
33+
## 3. Node.js
34+
35+
```bash
36+
nvm install
37+
nvm use
38+
```
39+
40+
## 4. Yarn
41+
42+
Yarn is the package manager used for dependency management of the Electron app and NextJS frontend.
43+
44+
```bash
45+
npm install --global yarn
46+
```
47+
48+
## 5. Python
49+
50+
Use Python 3.10 for the project.
51+
52+
```bash
53+
brew install [email protected]
54+
```
55+
56+
## 6. Pipx
57+
58+
```bash
59+
brew install pipx
60+
```
61+
62+
## 7. Poetry
63+
64+
```bash
65+
pipx install poetry
66+
```
67+
68+
If prompted to add the `poetry` command to your shell's config file, accept the prompt.
69+
70+
### Installing project dependencies
71+
72+
The `install-deps` script will install the dependencies for all parts of the project.
73+
The Electron app, the NextJS frontend, and the Python backend.
74+
75+
```bash
76+
yarn install-deps
77+
```
78+
79+
### Setup the .env file
80+
81+
Duplicate the `.env.example` file and rename it to `.env`.
82+
83+
```bash
84+
cp .env.example .env
85+
```
86+
87+
Then fill in the required environment variables.
88+
89+
- `NODE_ENV` - Set to `development` for development. `production` is only used for production builds built through the release script.
90+
- `FORK_URL` - Set to your desired HTTP RPC endpoint.
91+
- `DEV_RPC` - Set to the same value as `FORK_URL`.
92+
93+
### Run the project
94+
95+
```bash
96+
yarn dev
97+
```

‎docs/dev/rpcs.md

+43
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
# Acquiring RPC Endpoints for Development
2+
3+
## Tenderly
4+
5+
We use Tenderly to fork the Gnosis Mainnet chain for development purposes. This allows us to interact with the chain without risking real funds.
6+
7+
### 1. Create a Tenderly Account
8+
9+
Go to [Tenderly](https://tenderly.co/) and create an account.
10+
11+
### 2. Create a Project
12+
13+
Create a new project in Tenderly.
14+
15+
### 3. Fork the Gnosis Mainnet
16+
17+
1. Go to the _Forks_ section under the _Development_ tab in your Tenderly dashboard.
18+
19+
2. Click _Create Fork_.
20+
21+
3. Select "Gnosis Chain" as the network.
22+
23+
4. Use Chain ID `100`.
24+
25+
5. Copy the RPC URL provided by Tenderly.
26+
27+
### 4. Set the RPC URL
28+
29+
Set the `FORK_URL` and `DEV_RPC` environment variables in your `.env` file to the RPC URL provided by Tenderly.
30+
31+
### 5. Fund Your Accounts
32+
33+
Click the _Fund Accounts_ button in Tenderly to fund your accounts with XDAI (native token) and [OLAS](https://gnosisscan.io/token/0xce11e14225575945b8e6dc0d4f2dd4c570f79d9f).
34+
35+
### 6. Keeping Your Fork Up-to-Date
36+
37+
It is important to update your fork periodically to ensure that your forked chain is up-to-date with mainnet. You can do this by creating a new fork in Tenderly and updating your `FORK_URL` and `DEV_RPC` environment variables.
38+
39+
Alternatively, you can try the Tenderly's virtual testnet feature, which can automatically update your fork for you relative to mainnet. Though, this sometimes results in instability.
40+
41+
## Hardhat (deprecated)
42+
43+
Hardhat is a local alternative to Tenderly for forking EVM chains. It is useful for development purposes, though the chain state is lost once the Hardhat node is turned off.

0 commit comments

Comments
 (0)