From ad6b280b0a73f0f202022d07cc1830d4e625c2b5 Mon Sep 17 00:00:00 2001 From: Nick Frostbutter <75431177+nickfrosty@users.noreply.github.com> Date: Fri, 26 Aug 2022 22:03:48 -0400 Subject: [PATCH] [docs] Adding content pages under "developing" section (#26816) * feat: added intro to dApps and programs pages * style: removed whitespaces and updates MD syntax * fix: spellcheck * feat: what is rent page * fix: fix typos and removed whitespaces * fix: updated terminolgy * feat: added what is web 3 page * fix: removed dapps and web3 pages * feat: added links to the developing sidebar * fix: updated text based on comments * fix: fixed link --- docs/sidebars.js | 5 +++ docs/src/developing/intro/programs.md | 57 +++++++++++++++++++++++++++ docs/src/developing/intro/rent.md | 40 +++++++++++++++++++ docs/src/terminology.md | 12 +++++- 4 files changed, 113 insertions(+), 1 deletion(-) create mode 100644 docs/src/developing/intro/programs.md create mode 100644 docs/src/developing/intro/rent.md diff --git a/docs/sidebars.js b/docs/sidebars.js index 81ceb66f28..ae30b2d30d 100644 --- a/docs/sidebars.js +++ b/docs/sidebars.js @@ -81,6 +81,11 @@ module.exports = { id: "developing/programming-model/overview", label: "Overview", }, + { + type: "category", + label: "Getting Started", + items: ["developing/intro/programs", "developing/intro/rent"], + }, { type: "category", label: "Core Concepts", diff --git a/docs/src/developing/intro/programs.md b/docs/src/developing/intro/programs.md new file mode 100644 index 0000000000..7c0eb737f4 --- /dev/null +++ b/docs/src/developing/intro/programs.md @@ -0,0 +1,57 @@ +--- +title: What are Solana Programs? +description: "A Solana Program, aka smart contract, is the executable code that interprets the instructions on the blockchain. There are two types: Native and on chain." +keywords: "" +--- + +Solana Programs, often referred to as "_smart contracts_" on other blockchains, are the executable code that interprets the instructions sent inside of each transaction on the blockchain. They can be deployed directly into the core of the network as [Native Programs](#native-programs), or published by anyone as [On Chain Programs](#on-chain-programs). Programs are the core building blocks of the network and handle everything from sending tokens between wallets, to accepting votes of a DAOs, to tracking ownership of NFTs. + +Both types of programs run on top of the [Sealevel runtime](https://medium.com/solana-labs/sealevel-parallel-processing-thousands-of-smart-contracts-d814b378192), which is Solana's _parallel processing_ model that helps to enable the high transactions speeds of the blockchain. + +## Key points + +- Programs are essentially special type of [Accounts](../programming-model/accounts.md) that is marked as "_executable_" +- Programs can own other Accounts +- Programs can only _change the data_ or _debit_ accounts they own +- Any program can _read_ or _credit_ another account +- Programs are considered stateless since the primary data stored in a program account is the compiled BPF code +- Programs can be upgraded by their owner (see more on that below) + +## Types of programs + +The Solana blockchain has two types of programs: + +- Native programs +- On chain programs + +### On chain programs + +These user written programs, often referred to as "_smart contracts_" on other blockchains, are deployed directly to the blockchain for anyone to interact with and execute. Hence the name "on chain"! + +In effect, "on chain programs" are any program that is not baked directly into the Solana cluster's core code (like the native programs discussed below). + +And even though Solana Labs maintains a small subset of these on chain programs (collectively known as the [Solana Program Library](https://spl.solana.com/)), anyone can create or publish one. On chain programs can also be updated directly on the blockchain by the respective program's Account owner. + +### Native programs + +_Native programs_ are programs that are built directly into the core of the Solana blockchain. + +Similar to other "on chain" programs in Solana, native programs can be called by any other program/user. However, they can only be upgraded as part of the core blockchain and cluster updates. These native program upgrades are controlled via the releases to the [different clusters](../../cluster/overview.md). + +#### Examples of native programs include: + +- [System Program](../runtime-facilities/programs.md#system-program): Create new accounts, transfer tokens, and more +- [BPF Loader Program](../runtime-facilities/programs.md#bpf-loader): Deploys, upgrades, and executes programs on chain +- [Vote program](../runtime-facilities/programs.md#vote-program): Create and manage accounts that track validator voting state and rewards. + +## Executable + +When a Solana program is deployed onto the network, it is marked as "executable" by the [BPF Loader Program](../runtime-facilities/programs.md#bpf-loader). This allows the Solana runtime to efficiently and properly execute the compiled program code. + +## Upgradable + +Unlike other blockchains, Solana programs can be upgraded after they are deployed to the network. + +Native programs can only be upgraded as part of cluster updates when new software releases are made. + +On chain programs can be upgraded by the account that is marked as the "_Upgrade Authority_", which is usually the Solana account/address that deployed the program to begin with. diff --git a/docs/src/developing/intro/rent.md b/docs/src/developing/intro/rent.md new file mode 100644 index 0000000000..d26f93849c --- /dev/null +++ b/docs/src/developing/intro/rent.md @@ -0,0 +1,40 @@ +--- +title: What is rent? +description: "Rent: the small fee Solana accounts incur to store data on the blockchain. Accounts with >2 years of rent are rent exempt and do not pay the periodic fee." +keywords: "" +--- + +The fee every Solana Account to store data on the blockchain is called "_rent_". This _time and space_ based fee is required to keep an account, and its therefore its data, alive on the blockchain since [clusters](../../cluster/overview.md) must actively maintain this data. + +All Solana Accounts (and therefore Programs) are required to maintain a high enough LAMPORT balance to become [rent exempt](#rent-exempt) and remain on the Solana blockchain. + +When an Account no longer has enough LAMPORTS to pay its rent, it will be removed from the network in a process known as [Garbage Collection](#garbage-collection). + +> **Note:** Rent is different from [transactions fees](../../transaction_fees.md). Rent is paid (or held in an Account) to keep data stored on the Solana blockchain. Where as transaction fees are paid to process [instructions](../developing/../programming-model/transactions.md#instructions) on the network. + +### Rent rate + +The Solana rent rate is set on a network wide basis, primarily based on the set LAMPORTS _per_ byte _per_ year. + +Currently, the rent rate is a static amount and stored in the the [Rent sysvar](../runtime-facilities/sysvars.md#rent). + +## Rent exempt + +Accounts that maintain a minimum LAMPORT balance greater than 2 years worth of rent payments are considered "_rent exempt_" and will not incur a rent collection. + +> At the time of writing this, new Accounts and Programs **are required** to be initialized with enough LAMPORTS to become rent-exempt. The RPC endpoints have the ability to calculate this [estimated rent exempt balance](../clients/jsonrpc-api.md#getminimumbalanceforrentexemption) and is recommended to be used. + +Every time an account's balance is reduced, a check is performed to see if the account is still rent exempt. Transactions that would cause an account's balance to drop below the rent exempt threshold will fail. + +## Garbage collection + +Accounts that do not maintain their rent exempt status, or have a balance high enough to pay rent, are removed from the network in a process known as _garbage collection_. This process is done to help reduce the network wide storage of no longer used/maintained data. + +You can learn more about [garbage collection here](../../implemented-proposals/persistent-account-storage.md#garbage-collection) in this implemented proposal. + +## Learn more about Rent + +You can learn more about Solana Rent with the following articles and documentation: + +- [Implemented Proposals - Rent](../../implemented-proposals/rent.md) +- [Implemented Proposals - Account Storage](../../implemented-proposals/persistent-account-storage.md) diff --git a/docs/src/terminology.md b/docs/src/terminology.md index 5f612fee88..5145fd4867 100644 --- a/docs/src/terminology.md +++ b/docs/src/terminology.md @@ -225,7 +225,7 @@ The private key of a [keypair](#keypair). ## program -The code that interprets [instructions](#instruction). +The executable code that interprets the [instructions](#instruction) sent inside of each [transaction](#transaction) on the Solana. These programs are often referred to as "[_smart contracts_](./developing//intro/programs.md)" on other blockchains. ## program derived account (PDA) @@ -251,6 +251,16 @@ Transactions should request the minimum amount of compute units required for exe The public key of a [keypair](#keypair). +## rent + +Fee paid by [Accounts](#account) and [Programs](#program) to store data on the blockchain. When accounts do not have enough balance to pay rent, they may be Garbage Collected. + +See also [rent exempt](#rent-exempt) below. Learn more about rent here: [What is rent?](../src/developing/intro/rent.md). + +## rent exempt + +Accounts that maintain more than 2 years with of rent payments in their account are considered "*rent exempt*" and will not incur the [collection of rent](../src/developing/intro/rent.md#collecting-rent). + ## root A [block](#block) or [slot](#slot) that has reached maximum [lockout](#lockout) on a [validator](#validator). The root is the highest block that is an ancestor of all active forks on a validator. All ancestor blocks of a root are also transitively a root. Blocks that are not an ancestor and not a descendant of the root are excluded from consideration for consensus and can be discarded.