massalabs / massalabs/docs

Learn - Basic concepts content improvements

Open
#35 9 comments 0 reactions 2 assignees View on GitHub

@AurelienFT is already working on this.

Since May 19, 2023.

  • #55 by @loonggamma — merged
Dominant language
JavaScript
Stars
18
Forks
66
PR merge metrics
No merged PRs in 30d

Description

The context:

We took the current Massa docs section Architecture -> Introduction, and turned it into a new page which explains basic concepts of Massa blockchain.
The objective of the task is to create additional content, so that readers get a concise, not-too-techy introduction to Massa's main terminology.
Below I wrote suggestion on how to improve each sub-section.

The content structure can be found in this PR #34.

Sub-tasks (per sub-section in docs)

I suggest just linking small PRs for each or each few sections.

**1. Basic concepts → Ledger: -> DONE
To add:

  • a few sentences about ledger size limitations, and reasoning why we limit the size of Ledger.

2. Basic concepts → Address: -> DONE
To add:

  • Explain functionality of an address, simply, what it can do functionally.
  • Define the length of the address object in symbols;
  • Explain briefly how are addresses encrypted;
  • Explain prefixes in address naming;

3. Basic concepts → Smart Contract:
To add:

  • describe versioning of the SC
  • update the encryption paragraph as it will change with the testnet 24
  • Explain how SCs are different from addresses in terms of functionality (what permissions smart contracts have in terms of ledger read/write access, based on their address)
  • Why are they used - mention main use cases.

4. Basic concepts → Autonomous Smart Contract
To add:

  • description of the functionality of autonomous smart contracts on Massa
  • mention a few practical use-cases that would describe the value ASC brings
    to people familiar with workings of Smart contracts. -> DONE

5. Basic concepts → Storage cost section: -> DONE
To add:

  • describe how due to limited ledger space we introduce the storage cost
    concept.
  • describe who pays for the storage of smart contracts and how;
  • should be linked to the content in 3 sections above (Ledger, Address, SC)

6. Basic concepts → Operations section:
To add:

  • Describe what an operation is in a simple way.
  • Draw link to 'transactions' as called on other blockchains, so that the first time readers can understand it.
  • Mention the length of the Op hash on Massa blockchain. -> DONE

7. Basic concepts → Smart Contract → Execute SC operation:
To add:

  • A well described functionality of Execute SC, with a few key examples (~4-5 sentences).
  • Mention how Execute SC can be used to perform ledger changes without a need of deploying an SC. This is a unique Massa feature with a lot of usecases that can be mentioned and highlighted as a killer feature. -> DONE
  • Connect the content to the table of payload.

8. Basic concepts → Smart Contract → Call SC operation:
To add:

  • A well described functionality of Call SC, with a few key examples. (~4-5 sentences)
  • Connect the content to the table of payload.

9. Basic concepts → Smart Contract operations -> Tip (:::tip :::)
to add:

  • Give simple examples on when to use Execute and when Call SC.
  • Redirect to 'tutorials' section if we have any for these Operations

10. Basic concepts → Transaction fee
To add:

  • describe the concept of transaction fees at Massa and how the likelihood of Op being added to the block depends on it.
  • Introduce gas and gas limit
  • briefly introduce how transaction fees relate to gas and gas limit.
  • describe how transaction fees serve as rewards to Block creators/stakers.

11. Basic concepts → Block
To add:

  • Maximum block size -> DONE
  • Explain briefly final and stale blocks and redirect to learn [more](todo redirect to node-architecture.md -> Finalized blocks, stale blocks).

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.