guides structure & styling

_src/_assets/styles/_page-front.scss

@@ -5,7 +5,8 @@
 //
 
 .page-front {
-    .section--partners,
+    .section--guides,
+    .section--blog,
     .section-testimonials {
         @extend .background--darker;
     }

_src/_assets/styles/_page-guides.scss

@@ -0,0 +1,51 @@
+.content--guide {
+    h1,
+    h2,
+    h3,
+    h4 {
+        font-weight: $font-weight-normal;
+    }
+
+    h1 {
+        font-size: $font-size-h2;
+    }
+
+    h2 {
+        font-size: $font-size-h3;
+    }
+
+    h3 {
+        font-size: $font-size-h4;
+    }
+}
+
+.guide {
+    height: 100%;
+
+    a {
+        display: block;
+        box-shadow: none;
+        background: $brand-main-blue-dark;
+        padding: $spacer * 1.5 $spacer * 2;
+        height: 100%;
+        border-radius: $border-radius;
+
+        &:hover,
+        &:focus {
+            background: $brand-primary;
+
+            * {
+                color: $brand-main-blue-dark;
+            }
+        }
+    }
+}
+
+.guide__title,
+h1.guide__title {
+    font-size: $font-size-h4;
+    font-weight: $font-weight-normal;
+    margin-bottom: $spacer;
+    margin-top: 0;
+    color: $brand-primary;
+}

_src/_assets/styles/bigchain.scss

@@ -64,3 +64,4 @@
 @import 'page-faq';
 @import 'ipdb';
 @import 'oceanprotocol';
+@import 'page-guides';

_src/_data/getstarted.yml

@@ -51,7 +51,7 @@ drivers:
 # ----------------------------
 
 docs:
-    title: "Documentation"
+    title: "Documentation & Examples"
     description: "Dive into our documentation with tutorials, examples, terminology, references and more."
     button: "See All Documentation"
     categories:

_src/_guides/hitchhikers-guide.md

@@ -1,15 +0,0 @@
----
-layout: page
-
-title: The Hitchhiker's Guide to BigchainDB & IPDB
----
-
-If you’ve ever worked with databases or APIs, you’re likely familiar with CRUD. CRUD is short for Create, Read, Update, Delete. These are the basic operations of a persistent data store. So then, what’s ORM? ORM is an abstraction layer where database items are represented as programming language objects with variables as data, relations between items and functions that represent operations on that specific item in database. Django’s ORM is among the most famous ones:
-
-```
->>> Post.objects.create(author=me, title='Sample title', text='Test')
->>> Post.objects.all()
-<QuerySet [<Post: my post title>, <Post: another post title>, <Post: Sample title>]>
-```
-
-Now, blockchains alter this interface. They allow Create, as in creating an asset or minting a token. They allow Read, as in querying for a transaction using it’s ID. They don’t allow to Update or Delete anything that has been written though.

_src/_guides/how-to-connect-to-bigchaindb.md

@@ -0,0 +1,65 @@
+---
+layout: guide
+
+title: How to connect to BigchainDB
+description: Understand, how to get BigchainDB/IPDB up and running from the beginning to the end, so that you can start building applications on it
+image: image.jpg
+---
+
+## Connect to IPDB
+
+This part explains, how to connect to IPDB testnet
+(Good post https://medium.com/ipdb-blog/using-the-ipdb-test-network-a615f93d50a9)
+
+1. Create an account in IPDB and retrieve an app id etc.
+2. To connect to IPDB network you need your app_id & app_key. To get both, you need to register yourself in the following link https://developers.ipdb.io/signup
+3. Once done,
+
+```js
+const API_PATH = 'https://test.ipdb.io/api/v1/'
+const conn = new BigchainDB.Connection(API_PATH, {
+    app_id: 'your_app_id',
+    app_key: 'your_app_key'
+})
+```
+
+### Connect to REST API + Websocket
+
+https://docs.bigchaindb.com/projects/js-driver/en/latest/usage.html#websocket-event-stream-api-usage
+
+If you are connecting to a node that has support for the Event Stream API, you will be able to access real-time event streams over the WebSocket.
+
+Send a HTTP GET request to the node’s API Root Endpoint (e.g. http://localhost:9984/api/v1/) to check if the response the response contains a streams property:
+
+```js
+var wsUri = "ws://localhost:9985/api/v1/streams/valid_transactions";
+function init() {
+        websocket = new WebSocket(wsUri);
+        websocket.onmessage = function(evt) { onMessage(evt) };
+}
+function onMessage(evt) {
+        writeToScreen('<a href="#" class="list-group-item"><h4 class="list-group-item-heading">Valid Transaction</h4><p class="list-group-item-text">' + evt.data + '</p></a>');
+}
+function writeToScreen(message) {
+        var pre = document.createElement("p");
+        pre.style.wordWrap = "break-word";
+        pre.innerHTML = message;
+        output.appendChild(pre);
+}
+/* Initialize websocket and attach all events */
+window.addEventListener("load", init, false);
+```
+
+## Drivers and library
+
+This part in the journey contains everything that needs to be downloaded to be able to write an application in BigchainDB/IPDB (drivers, library etc.) => shortest path to get started
+
+Focus on JS driver in the beginning
+
+Basecally you just need to install the driver, for JS:
+
+```bash
+$ npm install bigchaindb-driver
+In case of python:
+$ pip3 install bigchaindb_driver
+```

_src/_guides/key-concepts-of-bigchaindb.md

@@ -0,0 +1,197 @@
+---
+layout: guide
+
+title: Key concepts of BigchainDB
+description: Understand the transaction model of BigchainDB (identity, inputs, outputs, assets, transactions)
+image: image.jpg
+---
+
+- Introduction: How do we structure data?
+- Explain asset-centric paradigm of bigchainDB
+- High-level components and relationship of components in a transaction => possibly illustrate with a graph, similar to CLI
+- Illustrate example we are going to use
+
+One of the most important aspects to understand about BigchainDB is how we structure our data. Traditional SQL databases structure data in tables, so the fundamental primitive is a table. NoSQL databases extend that by using other formats to structure data (e.g. JSON, key-values etc.). At BigchainDB, we structure data as assets. Our key principle is that everything can be represented as an asset. An asset can characterize any physical or digital object that you can think of (e.g. a car, a house, a data set or an intellectual property right).
+
+At it’s core, an asset is a JSON document containing information of a particular object (e.g. type of car, vehicle registration number etc.), representing that object in the digital world. An asset is usually owned by someone (user) and this ownership can be transferred to another person or entity in a transaction. A transaction has an input and an output. BigchainDB is therefore a system to digitally track ownership and transactions of ownership of assets. Ownership does not necessarily mean legal ownership. It can also be e.g. “temporary” ownership, such as a logistics company temporarily holding a product while transporting it to a warehouse and then “transferring” this temporary ownership to the warehouse. Sounds complicated? Don’t worry. That’s what this guide is here for.
+
+The only thing we want you to understand now, is that BigchainDB takes an asset-centric view and that our primitives are assets, inputs, outputs and transactions (more on that later). While traditionally, we design applications focusing on business processes (e.g. apps for booking & processing client orders, apps for tracking delivery of products etc.), in BigchainDB we don’t focus on processes, but on assets (e.g. a client order can be an asset that is then tracked across its entire lifecycle), which are transferred from one user to the next user. This influences much of how we build applications.
+
+Maybe insert graphic
+Maybe introduce an example that we can use for the entire section?
+
+Important: Every concept will contain links to the tutorials, where this concept is used and possibly also to the docs or blogposts for more details
+
+# Identity
+
+3.1.1 Description and definition
+What is a user in BDB? (public and private key pair)
+
+The first and most basic thing to understand in BigchainDB and Blockchain in general, is how a user is represented. While in traditional applications, a user is mapped as a username and a corresponding password, in BigchainDB, identity is represented as a combination of a public key (username) and private key (password).
+
+Explain public and private key
+
+A public key is an address that all users can see, just as your username. You use the public key as the address, where you direct a transaction to. The private key is used to create a digital signature for a transaction of an asset, to proof that you are the rightful (temporary) owner, resp. holder of this asset. Other users can use your public key to verify that this digital signature was generated using your private key. You can find more detailed descriptions of private and public key cryptography (insert link)
+Seems like we shouldn’t put here the name of our PKI’s parters
+
+Explain, that we don’t offer solutions for private/public key storage
+
+One of the main differences between private/public keys and usernames/passwords is that private keys are really only held by one user. There is no functionality that allows you to retrieve your private key, in case you lose it. Therefore, private keys need to be stored very safely. There is an entire industry focusing on providing solutions for safe storage of private keys. BigchainDB doesn’t offer a specific solution. It is the responsibility of the key holder to store it safely. A list of providers of safe key storage can be found here (insert link).
+
+Encrypting vs. Signing :
+
+When encrypting, you use their public key to write message and they use their private key to read it. Encryption helps ensure to protect sensitive data and preserve confidentiality and privacy
+
+When signing, you use your private key to write message's signature, and they use your public key to check if it's really yours. Signing data helps ensure: Data Integrity , Message Authentication (Proof of Origin) and Non-repudiation
+
+Include Decentralized Identify specification => tbd on wednesday
+DIF will work on a broad array of identity initiatives, ranging from a system to move identity away from centralized actors and provide decentralized access to services, to integrating blockchain technology with biometrics, to a utility-like service that links business processes with blockchain-based timestamps as a way of proving the identity and actions of users across organizations
+
+3.1.2 Code example
+Creation of a public/private key pair in JS (and maybe Py)
+Show, how to generate key pairs from a seed
+In Js from a seedPhrase:
+const keypair = new BigchainDB.Ed25519Keypair(bip39.mnemonicToSeed(seedPhrase).slice(0,32))
+
+Python :
+
+JS:
+3.2 Assets
+3.2.1 Description and definition
+What is an asset? => Link to docs for details (data model etc.)
+
+An asset can represent any physical or digital object from the real world. It can be a physical object like a car or a house or also a digital object like a customer order or an air mile. An asset can have one or multiple owners, but it can also be its own owner - think of e.g. an autonomous car or an IoT sensor that does transactions automatically. More information about the asset data model can be found here and here.
+
+How to move from a process to an asset-driven model? How to think with assets?
+What does an asset look like? (data model, graphical illustration)/How is an asset used in an application
+
+const assetdata = {
+        'bicycle': {
+                'serial_number': 'abcd1234',
+                'manufacturer': 'Bicycle Inc.',
+        }
+}
+
+How to use the asset and metadata field in an application:
+Explain difference between mutable and immutable elements of assets (mutable field and metadata)
+BigchainDB is an immutable database. It means that every asset you create will be there forever. An asset in BigchainDB contains two fields, the “asset” and the “metadata”. The asset field (mandatory) is something that you can never modify once you create it while the metadata field (optional) you will be able to modify it.
+There are two possibilities to update an asset:
+Make a transaction, so the metadata field can be updated.
+Create a new asset with new data pointing to the asset you want to modify
+Namespace (app/permission/type/instance/user)
+Query ALREADY IN FUNCTIONALITIES
+
+Schema
+Timestamp
+Values
+
+What types of assets exist?
+
+As already mentioned several times, assets can represent any types of object. This implies that there are different “models” of what an asset can represent.
+an asset as a claim (simple create with a message)
+In the most traditional and simple case, an asset could represent an ownership claim of a piece of art, a research paper or a Smart Contract. In this case, an asset is a digital certificate that user XYZ owns asset XYZ.
+an asset as a token (divisible assets - create your token launch on bigchainDB)
+Assets can also be divisible. This means that one asset can consist of different units. An asset can be divisible as many times as you wish.
+A token distribution event is a good example of a divisible asset in BigchainDB. You can do your own token distribution event on BigchainDB by issuing a divisible asset with a fixed supply of associated tokens.
+an asset as a versioned document (CRAB)
+An asset can also be a versioned document with the version state in the metadata field. The version of this document can be updated on a continuous base. Every time there is a new version of the document, it could be reflected in the metadata. The update would be a transfer transaction to the public key of the asset, where the transfer transaction contains the information about the version update in the metadata. For further information refer to (https://blog.bigchaindb.com/crab-create-retrieve-append-burn-b9f6d111f460)
+an asset as a time series (IOT devices that always append their latest value(s) as a TRANSFER, the current state is the unspent)
+An asset can also represent a time series of data. For instance, an IoT sensor records its own data. The IoT sensor is the asset and every submission of its data (e.g. temperature) is represented as a transfer transaction, where the metadata is updated with the latest temperature that the IoT sensor measured.
+an asset as finite state machine: each state transition is a transfer
+An asset can also represent a state machine where the state is represented in the metadata. Each time the machine changes it state, there is a transaction (possibility to listen to it with the websocket) changing the metadata to the state.
+An asset as a state (e.g. in smart contracts)
+An asset can represent the functionality or security of a smart contract. Every time the smart contracts changes, there is a transaction reflecting the new functionalities and securities of the updated smart contract. (Ref to Jolocom project)
+an asset as a supply chain tracker of an object
+Every single product can have a clear record of its history and verifiable authenticity.
+an asset as a permission (RBAC)
+Assets could be also: roles, users, messages, (and anything which can have multiple instances in a scenario — vehicles, reports, and so on). (https://blog.bigchaindb.com/role-based-access-control-for-bigchaindb-assets-b7cada491997)
+an asset as an access control token (eg API's check BDB if there is a token assigned to your pubkey)
+An
+an asset as an information channel (like the hashtag "#" on twitter - requires "link" - )
+An
+3.2.2 Code example
+Creation of an asset using JS (and maybe Py)
+const txCreateAliceSimple = driver.Transaction.makeCreateTransaction(
+        assetdata,
+        metadata,
+
+        // A transaction needs an output
+        [ driver.Transaction.makeOutput(
+                driver.Transaction.makeEd25519Condition(alice.publicKey))
+        ],
+        alice.publicKey
+)
+
+Include other drivers: cli, jave, ORM, graphql
+bdbOrm.myModel
+    .create({
+        keypair: aliceKeypair,
+        data: { key: 'dataValue' }
+    })
+    .then(asset => {
+        /*
+            asset is an object with all our data and functions
+            asset.id equals the id of the asset
+            asset.data is data of the last (unspent) transaction
+            asset.transactionHistory gives the full raw transaction history
+            Note: Raw transaction history has different object structure then
+            asset. You can find specific data change in metadata property.
+        */
+        console.log(asset.id)
+    })
+
+
+
+Things to remark:
+- The number of inputs = outputs in transaction
+- Outputs as locks and inputs as keys that unlock them
+- In a transaction you just work with one and just one asset. This will have to be changed in the future for Ocean, as several assets are needed in a transaction.
+- In divisible assets, you have to spend all of the inputs in a transaction, it means the inputs that you want to remain to yourself, you still need to send to yourself in the transaction.
+
+
+# Output
+
+3.3.1 Description and definition
+What is an output? => Link to docs for details (data model etc.)
+Frame functionally to show logic: an output describes conditions to acquire ownership of asset, incl. Some examples
+What are the components of an output (conditions, amount etc.)?
+
+3.3.2 Code example
+Representation of an output in JS (and maybe Py)
+
+# Input
+
+3.4.1 Description and definition
+What is an input? => Lused ink to docs for details (data model etc.)
+How to “spend” an output:
+Either by transferring ownership right
+Or, by updating its metadata
+What does an input look like? (data model, graphical illustration)
+What are the components of an input (owners before, fulfillment etc.)?
+
+3.4.2 Code example
+Representation of an input in JS (and maybe Py)
+
+# Transactions
+
+What are transactions in BigchainDB?
+What types of transactions are there in BigchainDB
+Show big picture for application developers: convert business processes to asset-centric flow with creates, transfers, links
+3.5.1 CREATE transaction
+3.5.1.2 Description and definition
+What is a create transaction?
+Operations of transactions (what is a create transaction used for?)
+What does a create transaction look like? (data model, graphical illustration)
+What are the components of a create transaction (previous owner etc.)?
+
+3.5.1.2 Code example
+Representation of a create transaction in JS (and maybe Py)
+3.5.2 TRANSFER transaction
+3.5.2.1 Description and definition
+What is a transfer transaction?
+Operations of transactions (what is a transfer transaction used for?)
+What does a transfer transaction look like? (data model, graphical illustration)
+What are the components of a transfer transaction (Asset ID etc.)?
+
+3.5.1.2 Code example
+Representation of a create transaction in JS (and maybe Py)

_src/_layouts/guide.html

@@ -0,0 +1,52 @@
+---
+layout: base
+---
+
+<header role="banner" class="header" {% if page.header %}style="background-image:url('/assets/img/{{ page.header }}')" {%
+    endif %}>
+
+    {% include menu-main.html %}
+
+    <div class="row">
+        <div class="header__content">
+            <h1 class="header__title">{{ page.title }}</h1>
+        </div>
+    </div>
+</header>
+
+<section role="main" class="content content--page">
+
+    <div class="row content--page--markdown content--guide">
+        {% if page.description %}
+            <header class="section-header">
+                <p class="section-description">{{ page.description }}</p>
+            </header>
+        {% endif %}
+
+        {{ content }}
+    </div>
+</section>
+
+<section class="section">
+    <div class="row">
+        <header class="section-header">
+            <h1 class="section-title">More guides</h1>
+        </header>
+    </div>
+    <div class="row">
+        <div class="grid grid--full grid-small--half grid--gutters">
+            {% for guide in site.guides | limit: 4 %}
+            <div class="grid__col">
+                <article class="guide">
+                    <a href="{{ guide.url }}">
+                        <h1 class="guide__title">{{ guide.title }}</h1>
+                    </a>
+                </article>
+            </div>
+            {% endfor %}
+        </div>
+    </div>
+    <div class="row text-center">
+        <a href="/guides/">All guides</a>
+    </div>
+</section>

_src/guides.html

@@ -2,15 +2,26 @@
 layout: page
 
 title: Guides
-tagline: Get up to speed with BigchainDB & IPDB
 ---
 
-{% for guide in site.guides %}
-
-<section class="section section--guide">
+<section class="section section--guides">
     <div class="row">
-        <a href="{{ guide.url }}">{{ guide.title }}</a>
+        <header class="section-header">
+            <p class="section-description">These guides explain you how to get started and build apps with BigchainDB/IPDB</p>
+        </header>
+    </div>
+    <div class="row row--wide">
+        <div class="grid grid--full grid-small--half grid--gutters">
+            {% for guide in site.guides %}
+                <div class="grid__col">
+                    <article class="guide">
+                        <a href="{{ guide.url }}">
+                            <h1 class="guide__title">{{ guide.title }}</h1>
+                            <p class="guide__description">{{ guide.description }}</p>
+                        </a>
+                    </article>
+                </div>
+            {% endfor %}
+        </div>
     </div>
 </section>
-
-{% endfor %}

_src/index.html

@@ -64,9 +64,31 @@ intro:
     </div>
 </section>
 
-{% include sections/section-testimonials.html %}
-
-{% include sections/section-cta-enterprise.html %}
+<section class="section section--guides">
+    <div class="row">
+        <header class="section-header">
+            <h1 class="section-title">Guides</h1>
+            <p class="section-description">Complete these guides to learn about how to create apps in BigchainDB.</p>
+        </header>
+    </div>
+    <div class="row row--wide">
+        <div class="grid grid--full grid-small--half grid--gutters">
+            {% for guide in site.guides | limit: 4 %}
+            <div class="grid__col">
+                <article class="guide">
+                    <a href="{{ guide.url }}">
+                        <h1 class="guide__title">{{ guide.title }}</h1>
+                        <p class="guide__description">{{ guide.description }}</p>
+                    </a>
+                </article>
+            </div>
+            {% endfor %}
+        </div>
+    </div>
+    <div class="row text-center">
+        <a class="btn btn-secondary" href="/guides/">All guides</a>
+    </div>
+</section>
 
 {% include sections/section-partners.html %}