iotaledger/iota-wiki

Restructure ISC docs

Closed this issue · 0 comments

jlvandenhout commented

This is the tracking issue for restructuring and reviewing the ISC docs. The structure is composed of the article structure, what sections each article should contain, and a description of what at least should be mentioned in each section.

Structure

  • Learn
    • Smart Contracts

      Focus on higher level introduction and explanation of the ISC protocol and components (what SCs, VM and nodes are and why they are needed).

      • Introduction

        Review of https://wiki.iota.org/learn/smart-contracts/introduction/

        • (Intro)
          • A short 3 or 4 line description of what smart contracts allow you to do.
          • Not too much jargon, preferably none.
          • An explanation the IOTA smart contract protocol extends the capabilities of the IOTA ledger (L1) by adding a scalable and programmable second layer (L2), allowing the execution of multiple smart contracts in parallel.
        • What smart contracts are
          • Smart contracts are programs that update state, and are executed by a committee of validators which keep track of the state.
          • Smart contracts are executed upon request, after which the committee comes to concensus about the resulting state update.
          • The state update is then committed to the history of state updates in the form of blocks, forming a block chain.
        • Code is law
          • Smart contracts are immutable.
          • Previous state, order of invokation, inputs, and resulting state update are deterministic.
          • Therefore the state and its history is verifiable, removing the need for trust between parties who rely on the state.
      • Protocol overview

        Consolidation of:

        • (Intro)
          • Explain the following is an overview of IOTA's smart contract solution: the IOTA smart contract protocol and the components of its implementation.
        • Smart contracts
          • They are programs containing functions to view the current state or produce a new state given the previous state and inputs.
          • They can be written in a multitude of languages, like Solidity, Rust or Go.
          • They get compiled to bytecode that can be run by a virtual machine.
        • Virtual machines
          • They take the current state and inputs, execute the bytecode and produce a new state.
          • They define the rules and restrictions smart contracts have to adhere to. (Sandbox interface explanation here).
          • Currently two virtual machines are implemented: the EVM (production ready) and the WASM VM (experimental).
        • Validators
          • Run virtual machines and store state and history of state.
          • Handle requests to run smart contracts on virtual machines.
          • Come to concensus about state updates.
          • Produce a block chain representing the history of state updates committed to.
        • State
          • The data, mutated by running smart contracts.
          • It is committed to a history of state updates in the form of a block, forming a block chain.
        • Block chains
          • Data structures of cryptographically linked blocks containing state updates.
          • Form a history of state updates up to the current state.
          • Are owned by chain owners.
          • Are produced by validators.
          • Are cryptograhpically anchored in the IOTA ledger, which allows parallel anchoring of chains and thus parallel execution of smart contracts on different chains.
      • Smart contract execution

        Consolidation of:

        • (Intro)
          • Short review that smart contracts are run by validators on request.
          • Mention the following is a description of what smart contracts and requests for running them look like.
        • Structure of a smart contract
          • Make sure fees are discussed for each type of function
          • Functions
          • View functions
        • Invoking a smart contract
          • Describe how fees are paid provided by requests
          • Off-ledger requests
          • On-ledger requests
      • Accounts, Addresses and Fees

        Review of https://wiki.iota.org/wasp-evm/explanations/how-accounts-work/

        • (Intro)
          • Review where accounts and addresses come from and where they exist.
        • Types of accounts
        • Fees
          • Make sure to explain gas budget
          • Make sure to explain gas fee
          • Make sure to explain allowance
          • Make sure to explain how the funds to pay for gas are "account funds - allowance"
      • Chain Owners, Validators, and Access Nodes

        Review of https://wiki.iota.org/learn/smart-contracts/validators/

        • (Intro)
          • Short description that there are different types of entities involved in operating a chain: chain owners, validator nodes, and access nodes.
        • Chain owners
          • Who chain owners are and their role in governing the chain and committee of validators.
        • Validator nodes
          • Have write access to the block chain, essentially making them block producers, responsible for calculating state updates of the chain.
          • They form a committee that each run smart contracts and reach concesus about state updates.
          • May be rotated by chain owners.
        • Access nodes
          • Have read access to the block chain.
          • Are able to respond to queries about the state.
          • Are able to forward requests to the committee.
      • Concensus

        Review of https://wiki.iota.org/learn/smart-contracts/consensus/

      • State management and anchoring

        Consolidation of:

        • (Intro)
          • Review of where state comes from and what it consists of.
          • Review that state updates form a block chain.
        • Digital assets
        • Data
        • Anchoring
  • Build
    • Smart Contracts

      Structured like the SDK docs with focus how to use available networks, APIs, tooling and built-in contracts, introduction to EVM (and WASM?) specifics of ISC.
      There are basically two options: we either have separate subsections for EVM and WASM VM, or we consolidate them into one "smart contract" subsection. Here is why I think we should consolidate:

      1. It's way more descriptive to have a "smart contract" subsection next to any other L2 solutions like Identity (yes, it's L2, it's just misplaced currently), instead of having "EVM" and "WASM VM", which don't tell much about the content.
      2. The core VM and its execution model are the same for both EVM and WASM VM, EVM and WASM VM are just "VM adaptors" or "core VM extentions" in that regard.
      3. From a developer standpoint EVM and WASM VM are just different targets to be used, depending on the choice of langauge and/or required capabilities, similar to how in the SDK different languages have different targets (Python -> Python interpreter; Typescript -> Browser, Node.js, or WASM; Rust -> x86, ARMv8, WASM, etc.)
      4. Deduplication of content as networks, chains, accounts, invokation, wasp-cli, etc are the same for both.
      5. Ability to be very specific about any differences or intricacies.
        I also think the schema tool and solo framework should be separate subsections like the wasp-cli, rather then being part of the smart contracts subsection, allowing proper introduction, define scope, have their own getting started, explanations and how-tos, etc.
      • About IOTA Smart Contracts

        Consolidation of:

        • (Intro)
          • A small reiteration of what smart contracts are.
          • Showcase specifics of the IOTA smart contracts protocol.
        • Languages and Virtual Machines
          • Give an overview of supported language and VM combinations.
          • Explain the libraries or core contracts needed for ISC specific functionality.
          • Give guidance on why you would choose one over the others.
          • Make sure there is a warning about decimals
        • Networks and chains
          • Indicate available network and chain options and compatibility.
          • Provide details like chain addresses, core contracts and chain IDs.
        • Tools
          • Solo
          • Schema tool
          • Wasp CLI
      • Getting Started
        • EVM
        • WASM VM
      • Explanations
        • Accounts and addresses
        • Core contracts
        • IOTA Smart Contract functionality
          • Explain ISC specific functionality and how it is provided.
          • Explain the Magic Contract
          • Explain WasmLib
      • How To

        In each how-to we provide code for each supported language using tabs, like in SDK docs.

      • API References
        • Core contracts
        • Magic Contract
        • WasmLib
  • Maintain