Merge pull request #3 from vsc-eco/feature/rework

Feature/rework

README.md

@@ -14,3 +14,28 @@ This command starts a local development server and opens up a browser window. Mo
 execute `./publish.sh` or just push to main (github actions workflow will take care of the rest)
 
 The repository needs to have its workflow permissions set to `read and write`, instead of the default vaule. Change that under the repositories settings -> Workflow permissions
+
+### TODO
+
+- [X] [Introduction.md](./docs/Introduction.md)
+- [ ] [core-philosophy.md](./docs/discussions/core-philosophy.md)
+- [ ] [dex.md](./docs/discussions/dex.md)
+- [X] [FAQ.md](./docs/discussions/FAQ.md)
+- [ ] [wrapping.md](./docs/discussions/wrapping.md)
+- [X] [generate-wallet.md](./docs/how-to/generate-wallet.md)
+- [X] [host-node.mdx](./docs/how-to/host-node.mdx)
+- [X] [api.md](./docs/references/api.md)
+- [X] [block-explorers.md](./docs/references/block-explorers.md)
+- [X] [client.md](./docs/references/client.md)
+- [ ] [contract-template.md](./docs/references/contract-template.md)
+- [X] [account-types.md](./docs/references/account-types.md)
+- [X] [examples.md](./docs/references/examples.md)
+- [X] [sdk.md](./docs/references/sdk.md)
+- [X] [first-contract.md](./docs/tutorials/first-contract.md)
+- [X] [invoke-contract.md](./docs/tutorials/invoke-contract.md)
+
+
+### Reminders
+
+- when contract deployment supports lite accounts, add to the documentation
+- move api documentation to the code a la js/ typedoc and just link to it, only manually add documentation to the doc here that describes how those components might be used (examples) or in conjunction

docs/Introduction.md

@@ -2,8 +2,92 @@
 sidebar_position: 1
 ---
 
-VSC (virtual smart chain) is a next generation smart contract L2 built on the Hive blockchain. VSC not only aims to bring smart contracts to Hive, but completely change the onboarding experience by introducing native lite accounts and cross chain login functionality, support decentralized and secure wrapping technology, and power the future of DAPPs on Hive. VSC operates as sidechain to Hive, this gives us a significant amount of flexibility to advance and build new features, along with the ability to scale the L2 network in the future. Using Hive as a clearing and synchronization method, VSC can push huge amounts of data with little to no overhead on the Hive L1. This approach allows VSC to inherit a lot of Hive's lower level functions such as feeless transactions and 3s block time. VSC uses Webassembly for smart contracts, which us to support any language that comiles down to native webassembly. The flexibility this gives to developers is emmense, where as EVM chains Solidity is the only option. Currently we support AssemblyScript (JavaScript like) with more languages to be added in the future as we vet and build out development tools for each programming language. 
+# Introduction
 
-Already, VSC will power fully decentralized and trustless Bitcoin wrapping, along with many others. The time is now to start building on VSC.
+## What is VSC?
 
-What do you think?
+VSC (virtual smart chain) is a next generation smart contract L2 built on the Hive blockchain. VSC not only aims to bring smart contracts to Hive, but completely change the onboarding experience by introducing native lite accounts and cross chain login functionality, support decentralized and secure wrapping technology, and power the future of DAPPs on Hive.  
+
+VSC operates as a sidechain to Hive, this gives us a significant amount of flexibility to advance and build new features, along with the ability to scale the L2 network in the future. Using Hive as a clearing and synchronization method, VSC can push huge amounts of data with little to no overhead on the Hive L1. This approach allows VSC to inherit a lot of Hive's lower level functions such as feeless transactions and 3s block time.  
+
+VSC uses Webassembly for smart contracts, which us to support any language that compiles down to native webassembly. The flexibility this gives to developers is emmense, where as EVM chains Solidity is the only option. Currently we support AssemblyScript (JavaScript like) with more languages to be added in the future as we vet and build out development tools for each programming language.  
+
+We want to make programming on HIVE easy, cheap and most importantly _available to everyone_.
+
+## Getting started
+
+We are in the early roots of the project. Nevertheless, we want to give you a pleasant onboarding experience to our ecosystem. Here you will find various guides that help you through your journey of discovering and experiencing the capabilities of the VSC ecosystem.
+
+### Create an account
+
+To get started create an _ed25519_ compatible private/ public key pair that will represent your wallet. Checkout [this](./how-to/generate-wallet.md) guide for how to do so. 
+
+### Write your first smart contract
+
+Writing your first contract is easy! Dive into the rabbit hole [here](./tutorials/first-contract.md).  
+
+## The ecosystem
+
+The VSC ecosystem continuously grows. Inform yourself about the components that are important for _you_ to build on top of VSC!
+
+### Block explorer
+
+Navigating a decentralized network without a block explorer would result in a highly negative user experience. Thereby we have [this section](./references/block-explorers.md) on block explorers, which gives you various information regarding this topic.  
+
+### VSC client
+
+To make it easy for developers to build applications that integrate the VSC network we have developed the VSC client. It bridges the gap between the end user facing web2 code and the web3 aspects of the VSC network. [Inform yourself here](./references/client.md).
+
+### Contract template
+
+The contract template is the development environment for your contracts. It contains various tools for testing and validating your contracts capabilities up to scripts for easy deployment to the VSC network. Read more [here](./references/contract-template.md).
+
+### VSC sdks
+
+One of the goals of VSC is to provide language-agnostic smart contract writing capabilities. For that reason we are using webassembly. Plain webassembly without any helper functions is just a little too primitive. Thereby we create VSC sdk's that expose and abstract basic functionalities like persistance or encryption in a library so that the developer doesn't need to care about those basic premises. [Read more about the implementations here](./references/sdk.md).
+
+## Topics of interest
+
+Here you can find a list of different points of interest.
+
+### Host your own node
+
+We need YOU. A decentralized network without node operators is like a democracy with one leader. That just doesn't feel right.  
+
+You help us to scale and make the network more secure.
+
+By participating in the VSC network you will receive reimbursements for your node operation.  
+
+Interested? [Checkout how to host a node here](./how-to/host-node.mdx).
+
+### Bitcoin wrapping
+
+VSC's mission extends beyond its innovative smart contract capabilities. It aspires to become the driving force behind the integration of various cryptocurrencies, starting with Bitcoin, into the HIVE ecosystem through a process known as wrapping. This approach paves the way for the seamless transfer and utilization of Bitcoin and potentially other cryptocurrencies within the HIVE network. [Read more here](./discussions/wrapping.md)
+
+### Dex
+
+We are building a decentralized exchange that allows users to exchange various currencies on top of your network. This is a crucial part of the VSC ecosystem as it allows users to exchange their assets in a decentralized manner. [Inform yourself about the current state here](./references/dex.md).
+
+### Account types
+
+One of our main goals is to improve the accessibility of smart contract creation and invocation. This is supported by the integration of various account types in the VSC network. Learn about [our supported authentication methods here](./references/account-types.md).
+
+### Contract example
+
+We have various example contracts/ applications that can be used as inspiration for your development journey. [You can see the full list here](./references/examples.md).
+
+### FAQ
+
+The most frequently asked questions get a spot in our FAQ document. This should be your entrypoint in case you are stuck. [Checkout the document here](./discussions/FAQ.md)
+
+## The architecture
+
+Here we give you an overview of the VSC architecture. This is important to understand the underlying principles of the VSC network.
+
+### API documentation
+
+The API of the VSC node can be queried for various information regarding the network. To get an overview of the available data checkout [this document](./references/api.md).
+
+### The VSC node
+
+The core principles of the VSC network, how they complement each other, and why we have chosen certain technologies is explained in detail [here](./discussions/core-philosophy.md).

docs/discussions/FAQ.md

@@ -0,0 +1,59 @@
+# FAQ
+
+## Do we supply node snapshots for node operators?
+
+No, you're node should sync up in ~1 day. If it takes significantly longer than that, contact us.
+
+## Are there any node rewards?
+
+Not yet. We have plans of doing a proof of burn model were node operators essentially buy credits to produce blocks. Then, when you produce blocks, you'd get a small reward on top of your initial investment.
+Note: We are not guaranteeing any specifics at the moment. This is subject to change as we do addition research.
+
+## When will I be able to deploy my token on VSC?
+
+We do not have a specific timeline for this.
+However, we are currently working on token and wrapping technology internally with HIVE, HBD, and BTC. Once all the kinks are ironed out with that, we will define public token standard(s) and create a reference implementation for each of those standard(s).
+
+## How do I run a node?
+
+Checkout [this repository](https://github.com/vsc-eco/vsc-deployment).
+
+## Why do I see Error: No withdrawals to process?
+
+This is typically normal, especially when your node is re-indexing. Most blocks don't generate withdrawals from the multisig, at the moment. In fact, at the time of writing, there should only be 1 withdrawal from vaultec, so you should see this message many times in your logs.
+
+## How do to update a node?
+
+Firstly, be sure to use the deployment from #4 ⁠faqs⁠ and then run sudo docker-compose up -d. This will pull the latest VSC node docker image automatically.
+
+## How to check if a node is up to date?
+
+`sudo docker-compose exec vsc-node cat .git/refs/heads/main`
+
+This will show you the commit you are on.
+
+Then you can compare it the latest commit in the vsc-node [GitHub repo](https://github.com/vsc-eco/vsc-node/commits/main/).
+
+## How do I migrate from the vsc-node repo to the vsc-deployment repo?
+
+1) cd ~/vsc-node (or where ever your vsc-node repo is)
+2) sudo docker-compose down
+3) sudo ./migrate.sh
+4) cd ../vsc-deployment (or where ever you set the new repo to be)
+5) sudo docker-compose up -d
+
+## How do I start writing a smart contract on VSC?
+
+This is our contract template. It should be enough to get started. There is usage and suggestions in [this repo](https://github.com/vsc-eco/contract-template) README.
+
+Also, [here is a DEX](https://github.com/vsc-eco/dex) that we are working on that tries to use/showcase best practices for writing VSC contracts.
+
+As for a formal docs site, we don't have that at the moment.
+
+However, you can checkout the AssemblyScript docs for usage of the smart contract language. It is very similar to TypeScript. Then, everything you need to interface with the VSC chain state is available in the @vsc.eco/sdk npm package.
+
+If you have any concrete suggestions about what we should include in a formal documentation site, please let us know.
+
+## Why is the documentation structured in this way?
+
+The documentation approach is based on the _Diátaxis_ principle. You can watch a summary about it [here](https://www.youtube.com/watch?v=t4vKPhjcMZg).

docs/how-to/generate-wallet.md

@@ -0,0 +1,13 @@
+# Generate wallet
+
+VSC on its layer 2 supports _ed25519_ compatible wallets. Those are called lite accounts in the context of VSC. They can be generated in various ways. Below you have the current recommended options.
+
+## Official wallet generator
+
+The offical recommended way to generate a lite account is via the wallet generator repository.
+
+It is based on NodeJS and is fairly lightweight.  
+
+Clone the repository, install the node modules and run the generator.
+
+Take a look at [the repository here](https://github.com/vsc-eco/wallet-generator).

docs/getting-started/Running a node.mdx → docs/how-to/host-node.mdx

@@ -1,47 +1,49 @@
----
-slug: running-a-node
-sidebar_position: 2
-
----
-
-<iframe  src="https://3speak.tv/embed?v=vsc.network/vqtkycsg" allow="accelerometer; autoplay; encrypted-media; gyroscope; picture-in-picture"></iframe>
-
-# Running a node
-
-This tutorial will guide you through the process of setting up a VSC node .
-
-Requirements:
-- Hive account (50HP, will rise in the future)
-- Technical knowledge of using a command line interface
-- Docker and docker-compose installed. Please see [https://docs.docker.com/get-docker/](https://docs.docker.com/get-docker/) for installation guide for docker. 
-
-System requirements are very low, in the future requirements will rise as network usage incrases.
-
-System requirements:
-- Raspberry pi 4 or better
-- 4 cores, 2GB ram or better
-
-
-The setup:
-
-1 ) `git clone https://github.com/vsc-eco/vsc-node`
-
-2 ) `cd vsc-node`
-
-3 ) < Fill in .env file here >
-
-You'll need to create a .env file with the following values from the .env.example file.
-
-```
-# Fill these in with your hive account details
-HIVE_ACCOUNT=Insert hive account username
-HIVE_ACCOUNT_POSTING=Insert hive account posting key
-HIVE_ACCOUNT_ACTIVE=Insert hive account active key
-```
-
-We generally recommend you use a different Hive account from your main account.
-
-
-4 ) `docker-compose up -d`
-
-You should be off to the races at this point! We can verify that your node is operating correctly on our discord server. Please actively monitor our Hive blog and discord server for incoming updates regarding VSC. You will need to consistent update your node as we release new versions of the software. Staying up to date with the rest of the network is critical in ensuring reliable operation of the network.
+# Running a node
+
+This document will guide you through the process of setting up a VSC node .
+
+## Prerequisites
+
+Requirements:
+- Hive account (50HP, will rise in the future)
+- Technical knowledge of using a command line interface
+- Docker and docker-compose installed. Please see [https://docs.docker.com/get-docker/](https://docs.docker.com/get-docker/) for installation guide for docker. 
+
+System requirements are very low, in the future requirements will rise as network usage incrases.
+
+System requirements:
+- Raspberry pi 4 or better
+- 4 cores, 2GB ram or better
+
+## Video guide
+
+<iframe src="https://3speak.tv/watch?v=vsc.network/uthosijv" allow="accelerometer; autoplay; encrypted-media; gyroscope; picture-in-picture; fullscreen"></iframe>
+
+## Setup
+
+The setup:
+
+1 ) `git clone https://github.com/vsc-eco/vsc-node`
+
+2 ) `cd vsc-node`
+
+3 ) < Fill in .env file here >
+
+You'll need to create a .env file with the following values from the .env.example file.
+
+```
+# Fill these in with your hive account details
+HIVE_ACCOUNT=Insert hive account username
+HIVE_ACCOUNT_POSTING=Insert hive account posting key
+HIVE_ACCOUNT_ACTIVE=Insert hive account active key
+```
+
+We generally recommend you use a different Hive account from your main account.
+
+
+4 ) `docker-compose up -d`
+
+You should be off to the races at this point! We can verify that your node is operating correctly on our discord server. Please actively monitor our Hive blog and discord server for incoming updates regarding VSC. You will need to consistent update your node as we release new versions of the software. Staying up to date with the rest of the network is critical in ensuring reliable operation of the network.
+
+You can disable automatic updates by setting the environment variable AUTO_UPDATE to false. However, we recommend to keep this feature enabled to ensure the node is always up-to-date. In our rapidly evolving ecosystem, it's crucial to keep the node updated for optimal network health.
+

docs/references/account-types.md

@@ -0,0 +1,23 @@
+# Account types
+
+The VSC network supports various account types for authentification.
+
+## DID | Private/ Public key
+
+You can authenticate yourself with an _ed25519_ compatible private/ public key pair.
+
+For a tutorial on how to generate such keys, please take a look at [this document](../how-to/generate-wallet.md).  
+
+## HIVE
+
+You can directly use your [HIVE](https://hive.io/) account to communicate with the VSC network.
+
+To register a HIVE account, you need someone with an existing account to invite you to the network.  
+
+This is also offered as a service by various providers. For more information please take a look at [HIVE's signup page](https://signup.hive.io/).
+
+## ETH
+
+We do support Ethereum based wallets.
+
+Create your Ethereum wallet via a [known provider](https://ethereum.org/en/wallets/) with access to your keys. We only support self-custodial wallets.