GitBook: [#79] Getting started first draft

SUMMARY.md

@@ -149,19 +149,18 @@
 
 ## DEVELOPERS
 
+* [Getting Started](developers/getting-started.md)
 * [Interfaces](developers/interfaces/README.md)
   * [ixo API Module](developers/interfaces/ixo-api-module.md)
   * [ixo BlockSync](developers/interfaces/ixo-blocksync.md)
-  * [ixo CellNode](developers/interfaces/ixo-cellnode.md)
-  * [ixo KeySafe](developers/interfaces/ixo-keysafe.md)
-  * [ixo Client SDK](developers/interfaces/ixo-client-sdk.md)
-  * [ixo Blockchain Interfaces](developers/interfaces/ixo-blockchain-interfaces.md)
 * [SDK's](developers/sdks/README.md)
+  * [ixo CellNode](developers/sdks/ixo-cellnode.md)
+  * [DID Module](developers/sdks/mobile-sdk.md)
+  * [ixo KeySafe](developers/sdks/ixo-keysafe.md)
+  * [ixo Client SDK](developers/sdks/ixo-client-sdk.md)
   * [Blockchain SDK](developers/sdks/blockchain/README.md)
-    * [Projects module](developers/sdks/blockchain/cells-module.md)
-    * [Bonds Module](developers/sdks/blockchain/claims-module.md)
-    * [Payments module](developers/sdks/blockchain/data-assets-module.md)
-    * [DID Module](developers/sdks/blockchain/mobile-sdk.md)
+    * [Fees Module](developers/sdks/blockchain/fees-module.md)
+  * [ixo Blockchain Interfaces](developers/sdks/ixo-blockchain-interfaces.md)
   * [Client SDK](https://github.com/ixofoundation/ixo-client-sdk)
 * [Developer Tools](developers/developer-tools/README.md)
   * [Prototyping](developers/developer-tools/prototyping.md)

developers/getting-started.md

@@ -0,0 +1,201 @@
+# Getting Started
+
+This document provides instructions for running a single node network on your local machine and then submitting your first few transactions to that network using the command line. Running a single node network is a great way to get familiar with ixo Blockchain and its functionality.
+
+### Prerequisites
+
+In order to install the `ixo` binary, you'll need the following:
+
+* Git `>=2`
+* Make `>=4`
+* Go `>=1.17`
+
+For more information, see Prerequisites.
+
+_Note: The `ixo` binary is installed into `$(go env GOPATH)/bin`, so make sure `$(go env GOPATH)/bin` is in your PATH (e.g. `export PATH=$(go env GOPATH)/bin:$PATH`)._
+
+### Install IXO
+
+The `ixo` binary serves as the node client and the application client. In other words, the `ixo` binary can be used to both run a node and interact with it.
+
+Clone the `ixo` repository:
+
+```bash
+git clone https://github.com/ixofoundation/ixo-blockchain
+```
+
+Change to the `genesis` directory:
+
+```bash
+cd ixo-blockchain
+```
+
+Check out the latest stable version:
+
+```bash
+git checkout master
+```
+
+Install the `ixo` binary:
+
+```bash
+make install
+```
+
+Check to make sure the install was successful:
+
+```bash
+ixod version
+```
+
+You should see `v1.0.8` printed to the console. Now that you have successfully installed the `ixo` binary, the next step will be to add a couple test accounts.
+
+### Quickstart
+
+If you would like to learn about the setup process and manually set up a single node network, skip to the next section. Alternatively, you can run the following quickstart script:
+
+```bash
+./scripts/start_testnode.sh
+```
+
+The script provides two command-line options for specifying a keyring-backend (`-k`), and the name of the blockchain (`-c`). For example, to use the `os` keyring-backend with the name `demo`:
+
+```bash
+./scripts/start_testnode.sh -k os -c demo
+```
+
+After running the quickstart script, you can skip to Start Node.
+
+### Create Accounts
+
+In this section, you will create two test accounts. You will name the first account `validator` and the second account `delegator`. You will create both accounts using the `test` backend, meaning both accounts will not be securely stored and should not be used in a production environment. When using the `test` backend, accounts are stored in the home directory (more on this in the next section).
+
+Create `validator` account:
+
+```bash
+ixod keys add validator --keyring-backend test
+```
+
+Create `delegator` account:
+
+```bash
+ixod keys add delegator --keyring-backend test
+```
+
+After running each command, information about each account will be printed to the console. The next step will be to initialize the node.
+
+### Initialize Node
+
+Initializing the node will create the `config` and `data` directories within the home directory. The `config` directory is where configuration files for the node are stored and the `data` directory is where the data for the blockchain is stored. The default home directory is `~/.ixod`.
+
+Initialize the node:
+
+```bash
+ixod init node --chain-id test
+```
+
+In this case, `node` is the name (or "moniker") of the node and `test` is the chain ID. Feel free to change these values but make sure to use the same value for `chain-id` in the following steps.
+
+### Update Genesis
+
+When the node was initialized, a `genesis.json` file was created within the `config` directory. In this section, you will be adding two genesis accounts (accounts with an initial token balance) and a genesis transaction (a transaction that registers the validator account in the validator set).
+
+Update native staking token to `uixo`:
+
+_For Mac OS:_
+
+```bash
+sed -i "" "s/stake/uixo/g" ~/.ixod/config/genesis.json
+```
+
+_For Linux variants:_
+
+```bash
+sed -i "s/stake/uixo/g" ~/.ixod/config/genesis.json
+```
+
+Add `validator` account to `genesis.json`:
+
+```bash
+ixod add-genesis-account validator 5000000000uixo --keyring-backend test
+```
+
+Add `delegator` account to `genesis.json`:
+
+```bash
+ixod add-genesis-account delegator 2000000000uixo --keyring-backend test
+```
+
+Create genesis transaction:
+
+```bash
+ixod gentx validator 1000000uixo --chain-id test --keyring-backend test
+```
+
+Add genesis transaction to `genesis.json`:
+
+```bash
+ixod collect-gentxs
+```
+
+Now that you have updated the `genesis.json` file, you are ready to start the node. Starting a node with a new genesis file will create a new blockchain.
+
+### Start Node
+
+Well, what are you waiting for?
+
+Start the node:
+
+```bash
+ixod start
+```
+
+You should see logs printed in your terminal with information about services starting up followed by blocks being produced and committed to your local blockchain.
+
+### Test Commands
+
+Now that you have a single node network running, you can open a new terminal window and interact with the node using the same `ixo` binary. Let's delegate some `uixo` tokens to the validator and then collect the rewards.
+
+Get the validator address for the `validator` account:
+
+```bash
+ixod keys show validator --bech val --keyring-backend test
+```
+
+Using the validator address, delegate some `uixo` tokens:
+
+```bash
+ixod tx staking delegate [validator_address] 10000000uixo --from delegator --keyring-backend test --chain-id test
+```
+
+In order to query all delegations, you'll need the address for the `delegator` account:
+
+```bash
+ixod keys show delegator --keyring-backend test
+```
+
+Using the address, query all delegations for the `delegator` account:
+
+```bash
+ixod q staking delegations [delegator_address]
+```
+
+Query the rewards using the delegator address and the validator address:
+
+```bash
+ixod q distribution rewards [delegator_address] [validator_address]
+```
+
+Withdraw the rewards:
+
+```bash
+ixod tx distribution withdraw-all-rewards --from delegator --keyring-backend test --chain-id test
+```
+
+Check the account balance:
+
+```bash
+ixod q bank balances [delegator_address]
+```
+
+You have successfully delegated `uixo` tokens to the `validator` account from the `delegator` account and then collected the rewards.

developers/interfaces/README.md

@@ -8,7 +8,7 @@ The ixo application stack provides interfaces for:
 
 * [ixo-apiModule](ixo-api-module.md) (NPM module)
 * [ixo-blocksync](ixo-blocksync.md) (Blockchain Indexing Database)
-* [ixo-CellNode](ixo-cellnode.md) (Decentralised Sovereign Data Store)
-* [ixo-blockchain](ixo-blockchain-interfaces.md) (Validator Node)
-* [ixo-Keysafe](ixo-keysafe.md) (Chrome browser extension)
+* [ixo-CellNode](../sdks/ixo-cellnode.md) (Decentralised Sovereign Data Store)
+* [ixo-blockchain](../sdks/ixo-blockchain-interfaces.md) (Validator Node)
+* [ixo-Keysafe](../sdks/ixo-keysafe.md) (Chrome browser extension)
 

developers/sdks/blockchain/fees-module.md

@@ -0,0 +1,119 @@
+# Fees Module
+
+## Fees
+
+The Entity Document `fees` property has the struct:
+
+```go
+type ProjectFeesMap struct {
+Context string `json:"@context" yaml:"@context"`
+Items   []struct {
+Type              FeeType `json:"@type" yaml:"@type"`
+PaymentTemplateId string  `json:"id" yaml:"id"`
+}
+}
+```
+
+Here is an example of how `fees` are specified in a project's `data`:
+
+```json
+"data": {
+    ...
+    "fees": {
+        "@context": "https://w3id.org/ixo/ns",
+        "items": [
+            {
+                "@type": "OracleFee",
+                "id":"payment:template:oracle-fee-template-1"
+            },
+            {
+                "@type": "FeeForService", 
+                "id":"payment:template:fee-for-service-template-1"
+            }
+        ]
+    }
+    ...
+}
+```
+
+The project-related fees currently supported are:
+
+* Oracle Fee (`OracleFee`)
+* Fee for Service (`FeeForService`)
+
+### General Approach
+
+The Entity Document `fees` property specifies one or more **payment template** IDs for pre-created payment templates. Each Payment Template specifies details such as the payment amounts, minimums, maximums, etc (see the payments module spec).
+
+For payments to be made requires the creation of a **payment contract**. Payment contracts effect `msgSend` transactions, when specific conditions are satisfied.
+
+The `processPay` function is used to create a contract and effect payments. A simplified version of this function is presented below:
+
+```go
+func processPay(keepers, projectDid, senderAddr, recipients, feeType, paymentTemplateId) {
+
+// Validate recipients
+recipients.Validate()
+
+// Get project address
+projectAddr := getProjectAccountAddress()
+
+// Get payment template
+template := paymentsKeeper.GetPaymentTemplate(paymentTemplateId)
+
+// Contruct payment contract ID
+contractId := "payment:contract:<moduleName>:<projectDid>:<senderAddr>:<feeType>"
+
+// Get an existing payment contract, or create a new contract
+if paymentsKeeper.ContractExists(contractId) {
+contract = paymentsKeeper.GetPaymentContract(contractId)
+} else {
+// Create a new contract with the constructed contractId. This points to a
+// specified payment template, with the project as the creator and payer in this example,
+// with the specified recipients. The contract cannot be deauthorised and is
+// by default authorised (i.e. can be effected by the contract creator).
+contract = payments.NewPaymentContract(contractId, paymentTemplateId,
+projectAddr, projectAddr, recipients, false, true)
+paymentsKeeper.SavePaymentContract(contract)
+}
+
+// Effect payment if conditons are met
+if contract.CanEffectPayment {
+// Check that project account has sufficient tokens to effect the payment contract
+if !bankKeeper.HasCoins(projectAddr, template.PaymentAmount) {
+return error("project has insufficient funds")
+}
+
+// Effect payment
+paymentsKeeper.EffectPayment(contractId)
+} else {
+return error("cannot effect contract payment (max reached?)")
+}
+}
+```
+
+The payment contract ID is automatically created using the following syntax:
+
+* Syntax: `payment:contract:<moduleName>:<projectDid>:<senderAddr>:<feeType>`
+* Example: `payment:contract:project:did:ixo:U7G...J8c:ixo107...0vx:OracleFee` Each payment contract is a unique instance for a module, project, sender address and fee type.
+
+Thus, if a new and unique set of the above 4 values is encountered, a new payment contract is created. Otherwise, the existing payment contract is fetched. This means that the project contract can (and is) used to persist information between two or more payments of the same type.
+
+An example use case is when we want to specify a maximum payment. Consider a contract created based on a payment template that specifies a pay amount of 100IXO and a maximum of 300IXO.
+
+1. In the first `processPay()` call, a new payment contract is created and immediately effected (cumulative pay: `100IXO`)
+2. In the second `processPay()` call, the payment contract already exists and is fetched and the payment is effected (cumulative pay: `200IXO`).
+3. In the third `processPay()` call, the cumulative pay will have reached the maximum `300IXO`.
+4. If a fourth `processPay()` call comes through, no further payment is effected, given that the contract cannot be effected due to the maximum being reached.
+
+If the project does not have enough funds to effect the payment contract, an error is returned by the function. An error is also returned if the payment contract payment cannot be effected.
+
+### Types of Fees
+
+#### Oracle Fee
+
+If an `oracle fee` payment template ID is specified when an entity is created, the oracle fee payment is made whenever an oracle processes a claim using the function `MsgCreateEvaluation`. Fees are automatically sent from the entity's project account to the oracle service-provider and any other fee recipient addresses specified in the payment contract.
+
+#### Fee for Service
+
+If a `fee-for-service` payment template ID is specified when an entity is created, the contract fee amount is automatically sent from the entity's project account to the service agent's account. The transaction is automatically processed when the service agent submits a claim, or when the claim status changes, depending on the condition for payment. For instance, the agent is paid when a claim is approved (the claim status updates to `1`) during `MsgCreateEvaluation` message flow.

guides/create-an-entity.md

@@ -55,7 +55,7 @@ Entity documents can be set up and published using the ixo client software. For
 
 The Entity Page contains information about your entity that you want end-users will view through web and mobile client software. Think of this as your entity's own web page. 
 
-![The user interface on ixo.world for configuring an entity page (for a Project)](<../.gitbook/assets/create a project template.png>)
+![The user interface on ixo.world for configuring an entity page (for a Project)](../.gitbook/assets/create-a-project-template.png)
 
 This information is input and displayed using cards. The default types of cards available are:
 
@@ -67,7 +67,7 @@ This information is input and displayed using cards. The default types of cards
 * Profiles card
 * Linked entities listing card
 
-![Example of the Profiles Card object in the ixo.world entity configuration UI](<../.gitbook/assets/profile card.png>)
+![Example of the Profiles Card object in the ixo.world entity configuration UI](../.gitbook/assets/profile-card.png)
 
 Cards accept plain text and render this in the pre-formatted style determined by the portal through which the page content is being viewed.&#x20;
 
@@ -89,7 +89,7 @@ Settings are what define the metadata and operating parameters for your entity.
 * Filter categories and tags
 * Claims templates for a range of claim types associated with the entity
 
-![](<../.gitbook/assets/settings creator.png>)
+![](../.gitbook/assets/settings-creator.png)
 
 ### Configure Advanced Settings