Skip to content
This repository was archived by the owner on Apr 4, 2023. It is now read-only.

Launch readme #86

Merged
merged 4 commits into from
Jan 20, 2022
Merged

Launch readme #86

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
cfc53a0
launch prep
patrick-ogrady Jan 20, 2022
ec659c1
making progress
patrick-ogrady Jan 20, 2022
4657d52
finish README
patrick-ogrady Jan 20, 2022
c6c3120
add some additional info about fees
patrick-ogrady Jan 20, 2022
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
186 changes: 115 additions & 71 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,78 +1,124 @@
# SpacesVM
# Spaces Virtual Machine (SpacesVM)

Avalanche is a network composed of multiple blockchains. Each blockchain is an instance
of a [Virtual Machine (VM)](https://docs.avax.network/learn/platform-overview#virtual-machines),
_Authenticated, Hierarchical Key-Value Store w/EIP-712 Compatibility,
Programmatic Expiry, Async Pruning, and Fee-Based Metering_

## Avalanche Subnets and Custom VMs
Avalanche is a network composed of multiple sub-networks (called subnets) that each contain
any number of blockchains. Each blockchain is an instance of a
[Virtual Machine (VM)](https://docs.avax.network/learn/platform-overview#virtual-machines),
much like an object in an object-oriented language is an instance of a class. That is,
the VM defines the behavior of the blockchain where it is instantiated. The use of
[Coreth (EVM)](https://github.com/ava-labs/coreth) on the [Avalanche C-Chain](https://docs.avax.network/learn/platform-overview)
is a canonical use case of a virtual machine (EVM) and its instantiation (C-Chain) on the Primary Subnet (Avalanche Mainnet). One
could deploy their own instance of the EVM as their own blockchain (to take
this to its logical conclusion.
the VM defines the behavior of the blockchain where it is instantiated. For example,
[Coreth (EVM)](https://github.com/ava-labs/coreth) is a VM that is instantiated by the
[Avalanche C-Chain](https://docs.avax.network/learn/platform-overview). Likewise, one
could deploy another instance of the EVM as their own blockchain (to take
this to its logical conclusion).

## Introduction
Just as Coreth powers the C-Chain, SpacesVM can be used to power its own
blockchain. However, instead of providing a place to execute smart contracts on
decentralized applications, SpacesVM enables anyone to store arbitrary data for
fast retrieval, like a Key-Value Database where a single party controls an
entire hierarchy of keys, you can claim your own hierarchy. (TODO).

You could build...
* Name Service
* Link Service
* dApp Metadata Backend
* Twitter Feed-like
* NFT Storage (value hashing)

## How it Works
### Action Types
#### Claim

##### Community support
blockchain in an Avalanche Subnet. Instead of providing a place to execute Solidity
smart contracts, however, SpacesVM enables authenticated, hierarchical storage of arbitrary
keys/values using any [EIP-712](https://eips.ethereum.org/EIPS/eip-712) compatible wallet.

#### Set/Delete
### Authenticated
All modifications of storage require the signature of the owner
of a "space"

##### Arbitrary Size File Support (using CLI)
### Hierarchical
Owners can modify any key in their "space" (ex: `owner/*`), however, no one
else can

#### Resolve
### Arbitrary Key/Value Storage
As long as a key is `^[a-z0-9]{1,256}$`, it can be used as an identifier in
SpacesVM. The max length of values is defined in genesis but typically ranges
between 64-200KB. Any number of values can be linked together to store files in
the > 100s of MBs range (as long as you have the `SPC` to pay for it).

#### Transfer
### EIP-712 Compatible
![wallet-signing](./imgs/wallet-signing.png)

#### Move
The canonical digest of a SpacesVM transaction is EIP-712 compliant, so any
Web3 wallet that can sign typed data can be used to interact with SpacesVM.

### Wallet Support: `eth_typedSignedData`
TODO: Insert image of signing using MM
## [Demo: https://tryspaces.xyz](https://tryspaces.xyz)
What better way to understand how the the SpacesVM works than to see it in action?
Well anon, you are in luck!

### Reserved Spaces
address space is reserved
You can try out the SpacesVM at [https://tryspaces.xyz)](https://tryspaces.xyz). All you need
is a EIP-712 Compatible Web3 Wallet (like MetaMask) and some `SPC` (all 973k of
you that interacted with the C-Chain more than 2 times got 10k `SPC` to get you
started).

### Content Addressing
SpacesVM verifies that values associated with keys that are length 66 (0x + hex-encoded keccak256 hash) are valid hashes.
This demo is running as an Avalanche Subnet on Fuji. It is **ALPHA LEVEL CODE** and may be
restarted/have a few bugs in it. It exists for demonstration purposes **ONLY**
but could be extended to run as a production-level Subnet on Avalanche Mainnet.

### Fee Mechanisms
Claim Desirability + Decay Rate
FeeUnits vs Load Units vs Expiry Units (per action)
## How it Works
### Claim
Interacting with the SpacesVM starts with a `ClaimTx`. This reserves your own
"space" and associates your address with it (so that only you can make changes
to it and/or the keys in it).

#### Reserved Spaces
Spaces of length 66 (`0x + hex-encoded EVM-style address`) are reserved for
address holders. Only the person who can produce a valid signature for a given
address can claim these types of spaces.

### Set/Delete
Once you have a space, you can then use `SetTx` and `DeleteTx` actions to
add/modify/delete keys in it. The more storage your space uses, the faster it
will expire.

#### Content-Addressable Keys
To support common blockchain use cases (like NFT storage), the SpacesVM
supports the storage of arbitrary size files using content-addressable keys.
You can try this out using `spaces-cli set-file <space> <filename>`.

### Lifeline
When your space uses a lot of storage and/or you've had it for a while, you may
need to extend its life using a `LifelineTx`. If you don't, your space will
eventually become inaccessible and all data stored within it will be deleted by
the SpacesVM.

#### Community Space Support
It is not required that you own a space to submit a `LifelineTx` that extends
its life. This enables the community to support useful spaces with their `SPC`.

### Resolve
When you want to view data stored in SpacesVM, you call `Resolve` on the value
path: `<space>/<key>`. If you stored a file at a particular path, use this
command to retrieve it: `spaces-cli resolve-file <path> <destination
filepath>`.

### Transfer
If you want to share some of your `SPC` with your friends, you can use
a `TransferTx` to send to any EVM-style address.

### Move
If you want to share a space with a friend, you can use a `MoveTx` to transfer
it to any EVM-style address.

### Space Rewards
Lottery allocation X% of fee
50% of the fees spent on each transaction are sent to a random space owner (as
long as the randomly selected recipient is not the creator of the transaction).

One could the SpacesVM to instead send rewards to a beneficiary chosen by
whoever produces a block.

One could easily modify this repository to instead send rewards to
beneficiaries chosen by whoever produces a block.
### Fees
All interactions with the SpacesVM require the payment of fees (denominated in
`SPC`). The VM Genesis includes support for allocating one-off `SPC` to
different EVM-style addresses and to allocating `SPC` to an airdrop list.

### Genesis Allocation -> public beta only
Airdrop `10,000 SPC` for anyone who has interacted with C-Chain more than
twice.
Nearly all fee-related params can be tuned by the SpacesVM deployer.

## Usage
_If you are interested in running the VM, not using it. Jump to [Running the
VM](#running-the-vm)._

Public Beta...

### tryspaces.xyz
What better way to understand how this works than to see it in action?

TODO: insert try spaces image + link

Hooked up to public beta
### [tryspaces.xyz](https://tryspaces.xyz)
The easiest way to try out SpacesVM is to visit the demo website
[trysapces.xyz](https://tryspaces.xyz).

### spaces-cli
#### Install
Expand Down Expand Up @@ -120,9 +166,9 @@ Use "spaces-cli [command] --help" for more information about a command.

##### Uploading Files
```
spaces-cli set-file patrick ~/Downloads/computer.gif -> patrick/6fe5a52f52b34fb1e07ba90bad47811c645176d0d49ef0c7a7b4b22013f676c8
spaces-cli resolve-file patrick/6fe5a52f52b34fb1e07ba90bad47811c645176d0d49ef0c7a7b4b22013f676c8 computer_copy.gif
spaces-cli delete-file patrick/6fe5a52f52b34fb1e07ba90bad47811c645176d0d49ef0c7a7b4b22013f676c8
spaces-cli set-file spaceslover ~/Downloads/computer.gif -> patrick/6fe5a52f52b34fb1e07ba90bad47811c645176d0d49ef0c7a7b4b22013f676c8
spaces-cli resolve-file spaceslover/6fe5a52f52b34fb1e07ba90bad47811c645176d0d49ef0c7a7b4b22013f676c8 computer_copy.gif
spaces-cli delete-file spaceslover/6fe5a52f52b34fb1e07ba90bad47811c645176d0d49ef0c7a7b4b22013f676c8
```

### [Golang SDK](https://github.com/ava-labs/spacesvm/blob/master/client/client.go)
Expand Down Expand Up @@ -460,29 +506,18 @@ _Can use this to get the current fee rate._
```

## Running the VM
To build the VM, run `./scripts/build.sh`.
To build the VM (and `spaces-cli`), run `./scripts/build.sh`.

### Joining the public beta
Put spacesvm binary in plugins dir
Add subnet-id to whitelisted-subnets

TODO: set bootstrap nodes

Here is an example config file:
--network-id=fuji

Make sure to add these commands when running the node:
--config-file

If you'd like to become a validator, reach out to @\_patrickogrady on Twitter
If you'd like to become a validator on the demo, reach out to @\_patrickogrady on Twitter
after you've joined the network and synced to tip. Please send a screenshot
indicating you've done this successfully.

### Running a local network
[`scripts/run.sh`](scripts/run.sh) automatically installs [avalanchego](https://github.com/ava-labs/avalanchego) to set up a local network
[`scripts/run.sh`](scripts/run.sh) automatically installs [avalanchego](https://github.com/ava-labs/avalanchego), sets up a local network,
and creates a `spacesvm` genesis file. To build and run E2E tests, you need to set the variable `E2E` before it: `E2E=true ./scripts/run.sh 1.7.4`

See [`tests/e2e`](tests/e2e) and [`tests/runner`](tests/runner) to see how it's set up and how its client requests are made:
_See [`tests/e2e`](tests/e2e) and [`tests/runner`](tests/runner) to see how it's set up and how its client requests are made._

```bash
# to startup a local cluster (good for development)
Expand Down Expand Up @@ -540,3 +575,12 @@ COMMENT
# to terminate the cluster
kill 12811
```

### Deploying Your Own Network
Anyone can deploy their own instance of the SpacesVM as a subnet on Avalanche.
All you need to do is compile it, create a genesis, and send a few txs to the
P-Chain.

You can do this by following [the tutorial
online](https://docs.avax.network/build/tutorials/platform/subnets/create-a-subnet/)
or by using the [subnet-cli](https://github.com/ava-labs/subnet-cli).
Binary file added imgs/wallet_signing.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.