Docs cleanup (#16964)

* Run lint:fix on docs

* Update dependencies

* Run prettier

* Run lint
This commit is contained in:
Justin Starry
2021-04-30 16:20:56 +08:00
committed by GitHub
parent 3d98321b38
commit 545e037e38
53 changed files with 23895 additions and 5418 deletions

View File

@@ -14,7 +14,7 @@ Unlike a file, the account includes metadata for the lifetime of the file. That
lifetime is expressed in "tokens", which is a number of fractional native
tokens, called _lamports_. Accounts are held in validator memory and pay
["rent"](#rent) to stay there. Each validator periodically scans all accounts
and collects rent. Any account that drops to zero lamports is purged. Accounts
and collects rent. Any account that drops to zero lamports is purged. Accounts
can also be marked [rent-exempt](#rent-exemption) if they contain a sufficient
number of lamports.
@@ -45,9 +45,9 @@ If an account is marked "executable" in its metadata then it is considered a
program which can be executed by including the account's public key an
instruction's [program id](transactions.md#program-id). Accounts are marked as
executable during a successful program deployment process by the loader that
owns the account. For example, during BPF program deployment, once the loader
owns the account. For example, during BPF program deployment, once the loader
has determined that the BPF bytecode in the account's data is valid, the loader
permanently marks the program account as executable. Once executable, the
permanently marks the program account as executable. Once executable, the
runtime enforces that the account's data (the program) is immutable.
## Creating
@@ -90,23 +90,23 @@ For security purposes, it is recommended that programs check the validity of any
account it reads but does not modify.
The security model enforces that an account's data can only be modified by the
account's `Owner` program. Doing so allows the program to trust that the data
passed to them via accounts they own will be in a known and valid state. The
account's `Owner` program. Doing so allows the program to trust that the data
passed to them via accounts they own will be in a known and valid state. The
runtime enforces this by rejecting any transaction containing a program that
attempts to write to an account it does not own. But, there are also cases
attempts to write to an account it does not own. But, there are also cases
where a program may merely read an account they think they own and assume the
data has only been written by themselves and thus is valid. But anyone can
data has only been written by themselves and thus is valid. But anyone can
issues instructions to a program, and the runtime does not know that those
accounts are expected to be owned by the program. Therefore a malicious user
accounts are expected to be owned by the program. Therefore a malicious user
could create accounts with arbitrary data and then pass these accounts to the
program in the place of a valid account. The arbitrary data could be crafted in
program in the place of a valid account. The arbitrary data could be crafted in
a way that leads to unexpected or harmful program behavior.
To check an account's validity, the program should either check the account's
address against a known value or check that the account is indeed owned
correctly (usually owned by the program itself).
One example is when programs read a sysvar. Unless the program checks the
One example is when programs read a sysvar. Unless the program checks the
address or owner, it's impossible to be sure whether it's a real and valid
sysvar merely by successful deserialization. Accordingly, the Solana SDK [checks
the sysvar's validity during
@@ -169,7 +169,6 @@ For example, an account is created with the initial transfer of 10,000 lamports
and no additional data. Rent is immediately debited from it on creation,
resulting in a balance of 7,561 lamports:
```text
Rent: 2,439 = 19.055441478439427 (rent rate) * 128 bytes (minimum account size) * 1 (epoch)
Account Balance: 7,561 = 10,000 (transfered lamports) - 2,439 (this account's rent fee for an epoch)

View File

@@ -5,8 +5,8 @@ title: Calling Between Programs
## Cross-Program Invocations
The Solana runtime allows programs to call each other via a mechanism called
cross-program invocation. Calling between programs is achieved by one program
invoking an instruction of the other. The invoking program is halted until the
cross-program invocation. Calling between programs is achieved by one program
invoking an instruction of the other. The invoking program is halted until the
invoked program finishes processing the instruction.
For example, a client could create a transaction that modifies two accounts,
@@ -57,7 +57,7 @@ given instruction to the `token` program via the instruction's `program_id`
field.
Note that `invoke` requires the caller to pass all the accounts required by the
instruction being invoked. This means that both the executable account (the
instruction being invoked. This means that both the executable account (the
ones that matches the instruction's program id) and the accounts passed to the
instruction procesor.
@@ -166,17 +166,17 @@ authority elsewhere at its discretion.
A Program address does not lie on the ed25519 curve and therefore has no valid
private key associated with it, and thus generating a signature for it is
impossible. While it has no private key of its own, it can be used by a program
impossible. While it has no private key of its own, it can be used by a program
to issue an instruction that includes the Program address as a signer.
### Hash-based generated program addresses
Program addresses are deterministically derived from a collection of seeds and a
program id using a 256-bit pre-image resistant hash function. Program address
program id using a 256-bit pre-image resistant hash function. Program address
must not lie on the ed25519 curve to ensure there is no associated private key.
During generation an error will be returned if the address is found to lie on
the curve. There is about a 50/50 change of this happening for a given
collection of seeds and program id. If this occurs a different set of seeds or
the curve. There is about a 50/50 change of this happening for a given
collection of seeds and program id. If this occurs a different set of seeds or
a seed bump (additional 8 bit seed) can be used to find a valid program address
off the curve.

View File

@@ -28,6 +28,7 @@ program only performed operations it was permitted to, and that the results
adhere to the runtime policy.
The policy is as follows:
- Only the owner of the account may change owner.
- And only if the account is writable.
- And only if the account is not executable
@@ -45,12 +46,13 @@ The policy is as follows:
## Compute Budget
To prevent a program from abusing computation resources each instruction in a
transaction is given a compute budget. The budget consists of computation units
transaction is given a compute budget. The budget consists of computation units
that are consumed as the program performs various operations and bounds that the
program may not exceed. When the program consumes its entire budget or exceeds
program may not exceed. When the program consumes its entire budget or exceeds
a bound then the runtime halts the program and returns an error.
The following operations incur a compute cost:
- Executing BPF instructions
- Calling system calls
- logging
@@ -59,7 +61,7 @@ The following operations incur a compute cost:
- ...
For cross-program invocations the programs invoked inherit the budget of their
parent. If an invoked program consume the budget or exceeds a bound the entire
parent. If an invoked program consume the budget or exceeds a bound the entire
invocation chain and the parent are halted.
The current [compute
@@ -81,6 +83,7 @@ log_pubkey_units: 100,
```
Then the program
- Could execute 200,000 BPF instructions if it does nothing else
- Could log 2,000 log messages
- Can not exceed 4k of stack usage
@@ -91,28 +94,28 @@ Since the compute budget is consumed incrementally as the program executes the
total budget consumption will be a combination of the various costs of the
operations it performs.
At runtime a program may log how much of the compute budget remains. See
At runtime a program may log how much of the compute budget remains. See
[debugging](developing/on-chain-programs/debugging.md#monitoring-compute-budget-consumption)
for more information.
The budget values are conditional on feature enablement, take a look the compute
budget's
[new](https://github.com/solana-labs/solana/blob/d3a3a7548c857f26ec2cb10e270da72d373020ec/sdk/src/process_instruction.rs#L97)
function to find out how the budget is constructed. An understanding of how
function to find out how the budget is constructed. An understanding of how
[features](runtime.md#features) work and what features are enabled on the
cluster being used are required to determine the current budget's values.
## New Features
As Solana evolves, new features or patches may be introduced that changes the
behavior of the cluster and how programs run. Changes in behavior must be
behavior of the cluster and how programs run. Changes in behavior must be
coordinated between the various nodes of the cluster, if nodes do not coordinate
then these changes can result in a break-down of consensus. Solana supports a
then these changes can result in a break-down of consensus. Solana supports a
mechanism called runtime features to facilitate the smooth adoption of changes.
Runtime features are epoch coordinated events where one or more behavior changes
to the cluster will occur. New changes to Solana that will change behavior are
wrapped with feature gates and disabled by default. The Solana tools are then
to the cluster will occur. New changes to Solana that will change behavior are
wrapped with feature gates and disabled by default. The Solana tools are then
used to activate a feature, which marks it pending, once marked pending the
feature will be activated at the next epoch.
@@ -124,5 +127,5 @@ solana feature status
```
If you encounter problems first ensure that the Solana tools version you are
using match the version returned by `solana cluster-version`. If they do not
using match the version returned by `solana cluster-version`. If they do not
match [install the correct tool suite](cli/install-solana-cli-tools.md).

View File

@@ -134,12 +134,11 @@ which loader should be used to load and execute the program and the data
contains information about how the runtime should execute the program.
In the case of [on-chain BPF programs](developing/on-chain-programs/overview.md),
the owner is the BPF Loader and the account data holds the BPF bytecode. Program
the owner is the BPF Loader and the account data holds the BPF bytecode. Program
accounts are permanently marked as executable by the loader once they are
successfully deployed. The runtime will reject transactions that specify programs
that are not executable.
Unlike on-chain programs, [Native Programs](/developing/runtime-facilities/programs)
are handled differently in that they are built directly into the Solana runtime.
@@ -173,21 +172,21 @@ token account states.
### Multiple instructions in a single transaction
A transaction can contain instructions in any order. This means a malicious
A transaction can contain instructions in any order. This means a malicious
user could craft transactions that may pose instructions in an order that the
program has not been protected against. Programs should be hardened to properly
program has not been protected against. Programs should be hardened to properly
and safely handle any possible instruction sequence.
One not so obvious example is account deinitialization. Some programs may
One not so obvious example is account deinitialization. Some programs may
attempt to deinitialize an account by setting its lamports to zero, with the
assumption that the runtime will delete the account. This assumption may be
assumption that the runtime will delete the account. This assumption may be
valid between transactions, but it is not between instructions or cross-program
invocations. To harden against this, the program should also explicitly zero out the
invocations. To harden against this, the program should also explicitly zero out the
account's data.
An example of where this could be a problem is if a token program, upon
transferring the token out of an account, sets the account's lamports to zero,
assuming it will be deleted by the runtime. If the program does not zero out the
assuming it will be deleted by the runtime. If the program does not zero out the
account's data, a malicious user could trail this instruction with another that
transfers the tokens a second time.
@@ -201,7 +200,6 @@ authorization to permit debiting the account or modifying its data. More
information about how the authorization is communicated to a program can be
found in [Accounts](accounts.md#signers)
## Recent Blockhash
A transaction includes a recent [blockhash](terminology.md#blockhash) to prevent