Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: Add initial docs for using Fruzhin in a web browser. #27

Merged
merged 1 commit into from
Sep 25, 2024
Merged

docs: Add initial docs for using Fruzhin in a web browser. #27

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
161 changes: 29 additions & 132 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,144 +1,41 @@
![Fruzhin-Cover-Black](https://github.com/LimeChain/Fruzhin/assets/29047760/8e617c9a-005d-44b7-b2bc-d14cc6860726)

Fruzhin is a Java Implementation of the Polkadot Host. The ultimate goal for Fruzhin is to be able to function as an
authoring and relaying node, increasing security of the Polkadot Protocol. It's been funded by
# What is Fruzhin?
Fruzhin is a Java implementation of the Polkadot Host. With the help of [TeaVM](https://teavm.org/) it is now available
as a JS based light client in web environments. It makes use of other full nodes to provide RPC server like behaviour.

It's been funded by
[Polkadot Pioneers Prize](https://polkadot.polkassembly.io/child_bounty/238).
> **Warning**
> Fruzhin is in pre-production state

# Status

- [x] Light Client
- [x] Full Node
- [ ] Authoring Node
- [ ] Relaying Node

# Getting started

## Clone

```bash
git clone https://github.com/LimeChain/Fruzhin.git
cd Fruzhin
```

## Setup & Build steps

### Java Version

Fruzhin only works with Java 21.

If you have multiple java version installed please make sure you're using 21:

```
export JAVA_HOME=`/usr/libexec/java_home -v 21`
```

### Build

```bash
./gradlew build
```

## Running Fruzhin

### Sync with official chain

```bash
java -jar build/libs/Fruzhin-0.1.0.jar -n polkadot --node-mode full --sync-mode full
```

- `-n`(network) could be `westend`, `polkadot` or `kusama`
- `--node-mode` could be `full` or `light`
- `--sync-mode` could be `full` or `warp`


## Get docker image

```bash
docker image pull limechain/fruzhin
docker volume create rocksdb
```

### Run Fruzhin on docker
```bash
docker run -d -v rocksdb:/usr/app/rocks-db limechain/fruzhin -n polkadot --node-mode full --sync-mode full
```

### Local development
In order to use the Fruzhin node for local development you will first need to start another node that would serve as a
peer.

For the sake of this example we will use [Paritytech's implementation](https://github.com/paritytech/polkadot-sdk).
If you are not familiar with how to run a node see [this](https://wiki.polkadot.network/docs/maintain-sync#setup-instructions).

Once you have successfully built the Polkadot project run the node via ``polkadot --dev``.
(The node starts on port 9944 by default)

Now you have 2 options:
- Use the automated `local_dev.sh` script
- Manual setup.

#### Automated script
1. Install [JQ](https://github.com/jqlang/jq).

`sudo apt-get install jq` Ubuntu

`brew install jq` MacOS

2. Head to the main directory of Fruzhin execute the script `./local_dev.sh`.

#### Manual setup
1. Fetch the chain spec

```bash
curl -H "Content-Type: application/json" -d '{"id":1, "jsonrpc":"2.0", "method": "sync_state_genSyncSpec", "params": [true]}' http://localhost:9944
```

The `lightSyncState` field is important for the light client to
work. Without it, the light client won't have a checkpoint to start from
and could be long-range attacked

2. Create a new `westend-local.json` inside of the `src/main/webapp/genesis` project directory.
3. Copy the contents of the `result` field from the fetched chain spec into the newly created `westend-local.json`.
4. In order to comply with the project requirements change the json structured as follows:

Fetched chain spec
```JSON
{
"genesis": {
"raw": {
"top": {},
"childrenDefault": {}
}
}
}
```
# Example
## Starting Fruzhin
In order to use Fruzhin in your webpage you have to import the appropriate JS files from UNKPG. Then you can call the
`fruzhin.main()` method with a string array parameter that takes one entry. The parameter can be one of the following:
- Well known chain name (polkadot, westend, kusama)
- A chain spec string

Desired chain spec
```JSON
{
"genesis": {
"top": {},
"childrenDefault": {}
}
}
```html
<!DOCTYPE html>
<html>
<head>
<title>Fruzhin</title>
<script type="module" src="https://unpkg.com/fruzhin/dist/js/fruzhin-lib.js"></script>
</head>
<body>
<script type="module">
fruzhin.main(['polkadot']);
</script>
</body>
</html>
```

5. Fetch the local boot nodes.
## Making RPC calls
Once Fruzhin is started an RPC client is exported under a `wsRpc` object. Making a call is easy.

```bash
curl -H "Content-Type: application/json" -d '{"id":1, "jsonrpc":"2.0", "method": "system_localListenAddresses"}' http://localhost:9944
```
`wsRpc.send('{"jsonrpc":"2.0","id":1,"method":"system_name","params":[]}')`

Paste the response into the `bootNodes` field of the `westend-local.json` chain spec.
Then the response can be retrieved by calling `wsRpc.nextResponse()`.

#### Build & Run
1. Build project
```
./gradlew build
```
2. Run Fruzhin
```
java -jar build/libs/Fruzhin-0.1.0.jar -n 'local' --node-mode 'full'/'light' --sync-mode 'full'/'warp' --db-recreate true/false
```
*NOTE* `wsRpc.nextResponse()` returns `null` if no response is present in the queue.
Loading