Docs cleanup (#16964)
* Run lint:fix on docs * Update dependencies * Run prettier * Run lint
This commit is contained in:
@@ -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)
|
||||
|
@@ -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.
|
||||
|
||||
|
@@ -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).
|
||||
|
@@ -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
|
||||
|
Reference in New Issue
Block a user