blockworks-foundation
/
solana
mirror of https://github.com/blockworks-foundation/solana.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

Grammar corrections (#23206) 

* Accounts page grammar edits

* Runtime page grammar edits

* calling-between-programs page grammar edits

* transactions page grammar edits

* small changes with e.g. following Chicago Manual
This commit is contained in:
Masaya Funakoshi 2022-02-22 18:23:47 -05:00 committed by GitHub
parent 20d031e2b8
commit ff604efc44
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
5 changed files with 633 additions and 553 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1090
docs/src/developing/clients/jsonrpc-api.md
View File

File diff suppressed because it is too large Load Diff

18
docs/src/developing/programming-model/accounts.md
View File

@ -24,9 +24,9 @@ uses an _address_ to look up an account. The address is a 256-bit public key.
## Signers ## Signers
Transactions may include digital [signatures](terminology.md#signature) Transactions may include digital [signatures](terminology.md#signature)
corresponding to the accounts' public keys referenced by the transaction. Such corresponding to the account's public keys referenced by the transaction. Such
signatures signify that the holder of the signatures signify that the holder of the
account's private key signed and thus "authorized" the transaction. In this case, account's private key signed, and thus, "authorized" the transaction. In this case,
the account is referred to as a _signer_. Whether an account is a signer or not the account is referred to as a _signer_. Whether an account is a signer or not
is communicated to the program as part of the account's metadata. Programs can is communicated to the program as part of the account's metadata. Programs can
then use that information to make authority decisions. then use that information to make authority decisions.
@ -71,7 +71,7 @@ previously created, the program will be passed an account with no data and zero
that is owned by the system program. that is owned by the system program.
Such newly created accounts reflect Such newly created accounts reflect
whether they sign the transaction and therefore can be used as an whether they sign the transaction, and therefore, can be used as an
authority. Authorities in this context convey to the program that the holder of authority. Authorities in this context convey to the program that the holder of
the private key associated with the account's public key signed the transaction. the private key associated with the account's public key signed the transaction.
The account's public key may be known to the program or recorded in another The account's public key may be known to the program or recorded in another
@ -85,14 +85,14 @@ System program and is called a _system account_ aptly. An account includes
"owner" metadata. The owner is a program id. The runtime grants the program "owner" metadata. The owner is a program id. The runtime grants the program
write access to the account if its id matches the owner. For the case of the write access to the account if its id matches the owner. For the case of the
System program, the runtime allows clients to transfer lamports and importantly System program, the runtime allows clients to transfer lamports and importantly
_assign_ account ownership, meaning changing owner to different program id. If _assign_ account ownership, meaning changing the owner to a different program id. If
an account is not owned by a program, the program is only permitted to read its an account is not owned by a program, the program is only permitted to read its
data and credit the account. data and credit the account.
## Verifying validity of unmodified, reference-only accounts ## Verifying validity of unmodified, reference-only accounts
For security purposes, it is recommended that programs check the validity of any For security purposes, it is recommended that programs check the validity of any
account it reads but does not modify. account it reads, but does not modify.
This is because a malicious user This is because a malicious user
could create accounts with arbitrary data and then pass these accounts to the could create accounts with arbitrary data and then pass these accounts to the
@ -101,17 +101,17 @@ a way that leads to unexpected or harmful program behavior.
The security model enforces that an account's data can only be modified by the The security model enforces that an account's data can only be modified by the
account's `Owner` program. This allows the program to trust that the data account's `Owner` program. This allows the program to trust that the data
passed to them via accounts they own. The is passed to them via accounts they own. The
runtime enforces this by rejecting any transaction containing a program that runtime enforces this by rejecting any transaction containing a program that
attempts to write to an account it does not own. attempts to write to an account it does not own.
If a program were to not check account validity, it might read an account If a program were to not check account validity, it might read an account
it thinks it owns but doesn't. Anyone can it thinks it owns, but doesn't. Anyone can
issue instructions to a program, and the runtime does not know that those issue instructions to a program, and the runtime does not know that those
accounts are expected to be owned by the program. accounts are expected to be owned by the program.
To check an account's validity, the program should either check the account's 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 address against a known value, or check that the account is indeed owned
correctly (usually owned by the program itself). correctly (usually owned by the program itself).
One example is when programs use a sysvar account. Unless the program checks the One example is when programs use a sysvar account. Unless the program checks the
@ -120,7 +120,7 @@ valid sysvar account merely by successful deserialization of the account's data.
Accordingly, the Solana SDK [checks the sysvar account's validity during Accordingly, the Solana SDK [checks the sysvar account's validity during
deserialization](https://github.com/solana-labs/solana/blob/a95675a7ce1651f7b59443eb146b356bc4b3f374/sdk/program/src/sysvar/mod.rs#L65). deserialization](https://github.com/solana-labs/solana/blob/a95675a7ce1651f7b59443eb146b356bc4b3f374/sdk/program/src/sysvar/mod.rs#L65).
A alternative and safer way to read a sysvar is via the sysvar's [`get()` An alternative and safer way to read a sysvar is via the sysvar's [`get()`
function](https://github.com/solana-labs/solana/blob/64bfc14a75671e4ec3fe969ded01a599645080eb/sdk/program/src/sysvar/mod.rs#L73) function](https://github.com/solana-labs/solana/blob/64bfc14a75671e4ec3fe969ded01a599645080eb/sdk/program/src/sysvar/mod.rs#L73)
which doesn't require these checks. which doesn't require these checks.

22
docs/src/developing/programming-model/calling-between-programs.md
View File

@ -30,8 +30,8 @@ let message = Message::new(vec![
client.send_and_confirm_message(&[&alice_keypair, &bob_keypair], &message); client.send_and_confirm_message(&[&alice_keypair, &bob_keypair], &message);
``` ```
Given two on-chain programs `token` and `acme`, each implementing instructions Given two on-chain programs, `token` and `acme`, each implementing instructions
`pay()` and `launch_missiles()` respectively, acme can be implemented with a `pay()` and `launch_missiles()` respectively, `acme` can be implemented with a
call to a function defined in the `token` module by issuing a cross-program call to a function defined in the `token` module by issuing a cross-program
invocation: invocation:
@ -66,12 +66,12 @@ state of the accounts at the beginning of the `acme`'s instruction. After
`pay()` completes, the runtime must again ensure that `token` didn't modify any `pay()` completes, the runtime must again ensure that `token` didn't modify any
accounts owned by `acme` by again applying the runtime's policy, but this time accounts owned by `acme` by again applying the runtime's policy, but this time
with the `token` program ID. Lastly, after `pay_and_launch_missiles()` with the `token` program ID. Lastly, after `pay_and_launch_missiles()`
completes, the runtime must apply the runtime policy one more time, where it completes, the runtime must apply the runtime policy one more time where it
normally would, but using all updated `pre_*` variables. If executing normally would, but using all updated `pre_*` variables. If executing
`pay_and_launch_missiles()` up to `pay()` made no invalid account changes, `pay_and_launch_missiles()` up to `pay()` made no invalid account changes,
`pay()` made no invalid changes, and executing from `pay()` until `pay()` made no invalid changes, and executing from `pay()` until
`pay_and_launch_missiles()` returns made no invalid changes, then the runtime `pay_and_launch_missiles()` returns made no invalid changes, then the runtime
can transitively assume `pay_and_launch_missiles()` as whole made no invalid can transitively assume `pay_and_launch_missiles()` as a whole made no invalid
account changes, and therefore commit all these account modifications. account changes, and therefore commit all these account modifications.
### Instructions that require privileges ### Instructions that require privileges
@ -111,12 +111,12 @@ To sign an account with program derived addresses, a program may
### Call Depth ### Call Depth
Cross-program invocations allow programs to invoke other programs directly but Cross-program invocations allow programs to invoke other programs directly, but
the depth is constrained currently to 4. the depth is constrained currently to 4.
### Reentrancy ### Reentrancy
Reentrancy is currently limited to direct self recursion capped at a fixed Reentrancy is currently limited to direct self recursion, capped at a fixed
depth. This restriction prevents situations where a program might invoke another depth. This restriction prevents situations where a program might invoke another
from an intermediary state without the knowledge that it might later be called from an intermediary state without the knowledge that it might later be called
back into. Direct recursion gives the program full control of its state at the back into. Direct recursion gives the program full control of its state at the
@ -159,22 +159,22 @@ Program derived address:
present in instructions invoked via [Cross-Program Invocations](#cross-program-invocations). present in instructions invoked via [Cross-Program Invocations](#cross-program-invocations).
Given the two conditions, users can securely transfer or assign the authority of Given the two conditions, users can securely transfer or assign the authority of
on-chain assets to program addresses and the program can then assign that on-chain assets to program addresses, and the program can then assign that
authority elsewhere at its discretion. authority elsewhere at its discretion.
### Private keys for program addresses ### Private keys for program addresses
A Program address does not lie on the ed25519 curve and therefore has no valid 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 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. to issue an instruction that includes the program address as a signer.
### Hash-based generated program addresses ### Hash-based generated program addresses
Program addresses are deterministically derived from a collection of seeds and a 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. 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 During generation, an error will be returned if the address is found to lie on
the curve. There is about a 50/50 chance of this happening for a given the curve. There is about a 50/50 chance of this happening for a given
collection of seeds and program id. If this occurs a different set of seeds or 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 a seed bump (additional 8 bit seed) can be used to find a valid program address
@ -184,7 +184,7 @@ Deterministic program addresses for programs follow a similar derivation path as
Accounts created with `SystemInstruction::CreateAccountWithSeed` which is Accounts created with `SystemInstruction::CreateAccountWithSeed` which is
implemented with `Pubkey::create_with_seed`. implemented with `Pubkey::create_with_seed`.
For reference that implementation is as follows: For reference, that implementation is as follows:
```rust,ignore ```rust,ignore
pub fn create_with_seed( pub fn create_with_seed(

46
docs/src/developing/programming-model/runtime.md
View File

@ -12,18 +12,18 @@ signed the transaction using the keypair's _private key_, it knows the client
authorized the token transfer. authorized the token transfer.
In other words, the entire set of accounts owned by a given program can be In other words, the entire set of accounts owned by a given program can be
regarded as a key-value store where a key is the account address and value is regarded as a key-value store, where a key is the account address and value is
program-specific arbitrary binary data. A program author can decide how to program-specific arbitrary binary data. A program author can decide how to
manage the program's whole state as possibly many accounts. manage the program's whole state, possibly as many accounts.
After the runtime executes each of the transaction's instructions, it uses the After the runtime executes each of the transaction's instructions, it uses the
account metadata to verify that the access policy was not violated. If a program account metadata to verify that the access policy was not violated. If a program
violates the policy, the runtime discards all account changes made by all violates the policy, the runtime discards all account changes made by all
instructions in the transaction and marks the transaction as failed. instructions in the transaction, and marks the transaction as failed.
### Policy ### Policy
After a program has processed an instruction the runtime verifies that the After a program has processed an instruction, the runtime verifies that the
program only performed operations it was permitted to, and that the results program only performed operations it was permitted to, and that the results
adhere to the runtime policy. adhere to the runtime policy.
@ -31,7 +31,7 @@ The policy is as follows:
- Only the owner of the account may change owner. - Only the owner of the account may change owner.
- And only if the account is writable. - And only if the account is writable.
- And only if the account is not executable - And only if the account is not executable.
- And only if the data is zero-initialized or empty. - And only if the data is zero-initialized or empty.
- An account not assigned to the program cannot have its balance decrease. - An account not assigned to the program cannot have its balance decrease.
- The balance of read-only and executable accounts may not change. - The balance of read-only and executable accounts may not change.
@ -45,15 +45,11 @@ The policy is as follows:
## Compute Budget ## Compute Budget
To prevent a program from abusing computation resources each instruction in a 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 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 a program may not exceed. When the program consumes its entire budget or exceeds
bound then the runtime halts the program and returns an error. a bound, then the runtime halts the program and returns an error.
Note: The compute budget currently applies per-instruction but is moving toward
a per-transaction model. For more information see [Transaction-wide Compute
Budget](#transaction-wide-compute-buget).
The following operations incur a compute cost: The following operations incur a compute cost:
@ -65,8 +61,8 @@ The following operations incur a compute cost:
- ... - ...
For cross-program invocations, the programs invoked inherit the budget of their 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 consumes the budget or exceeds a bound, the entire
invocation chain is halted. invocation chain and the parent are halted.
The current [compute The current [compute
budget](https://github.com/solana-labs/solana/blob/0224a8b127ace4c6453dd6492a38c66cb999abd2/sdk/src/compute_budget.rs#L102) budget](https://github.com/solana-labs/solana/blob/0224a8b127ace4c6453dd6492a38c66cb999abd2/sdk/src/compute_budget.rs#L102)
@ -89,10 +85,10 @@ log_pubkey_units: 100,
Then the program Then the program
- Could execute 200,000 BPF instructions if it does nothing else - Could execute 200,000 BPF instructions, if it does nothing else.
- Could log 2,000 log messages - Could log 2,000 log messages.
- Can not exceed 4k of stack usage - Can not exceed 4k of stack usage.
- Can not exceed a BPF call depth of 64 - Can not exceed a BPF call depth of 64.
- Cannot exceed 4 levels of cross-program invocations. - Cannot exceed 4 levels of cross-program invocations.
Since the compute budget is consumed incrementally as the program executes, the Since the compute budget is consumed incrementally as the program executes, the
@ -106,7 +102,7 @@ for more information.
## Transaction-wide Compute Budget ## Transaction-wide Compute Budget
Transactions are processed as a single entity and are the primary unit of block Transactions are processed as a single entity and are the primary unit of block
scheduling. In order to facilitate better block scheduling and account for the scheduling. In order to facilitate better block scheduling and account for the
computational cost of each transaction, the compute budget is moving to a computational cost of each transaction, the compute budget is moving to a
transaction-wide budget rather than per-instruction. transaction-wide budget rather than per-instruction.
@ -114,16 +110,16 @@ For information on what the compute budget is and how it is applied see [Compute
Budget](#compute-budget). Budget](#compute-budget).
With a transaction-wide compute budget the `max_units` cap is applied to the With a transaction-wide compute budget the `max_units` cap is applied to the
entire transaction rather than to each instruction within the transaction. The entire transaction rather than to each instruction within the transaction. The
default number of maximum units remains at 200k which means the sum of the default number of maximum units remains at 200k which means the sum of the
compute units used by each instruction in the transaction must not exceed that compute units used by each instruction in the transaction must not exceed that
value. The number of maximum units allows is intentionally kept small to value. The number of maximum units allows is intentionally kept small to
facilitate optimized programs and form the bases for a minimum fee level. facilitate optimized programs and form the bases for a minimum fee level.
There are a lot of uses cases that require more than 200k units There are a lot of uses cases that require more than 200k units
transaction-wide. To enable these uses cases transactions can include a transaction-wide. To enable these uses cases transactions can include a
[``ComputeBudgetInstruction`](https://github.com/solana-labs/solana/blob/0224a8b127ace4c6453dd6492a38c66cb999abd2/sdk/src/compute_budget.rs#L44) [``ComputeBudgetInstruction`](https://github.com/solana-labs/solana/blob/0224a8b127ace4c6453dd6492a38c66cb999abd2/sdk/src/compute_budget.rs#L44)
requesting a higher compute unit cap. Higher compute caps will be charged requesting a higher compute unit cap. Higher compute caps will be charged
higher fees. higher fees.
Compute Budget instructions don't require any accounts and must lie in the first Compute Budget instructions don't require any accounts and must lie in the first
@ -140,7 +136,7 @@ let instruction = ComputeBudgetInstruction::request_units(300_000);
As Solana evolves, new features or patches may be introduced that changes the 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 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. mechanism called runtime features to facilitate the smooth adoption of changes.
@ -157,6 +153,6 @@ tools](cli/install-solana-cli-tools.md):
solana feature status solana feature status
``` ```
If you encounter problems first ensure that the Solana tools version you are 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). match, [install the correct tool suite](cli/install-solana-cli-tools.md).

10
docs/src/developing/programming-model/transactions.md
View File

@ -43,7 +43,7 @@ not requiring signatures.
#### Account Addresses Format #### Account Addresses Format
The addresses that require signatures appear at the beginning of the account The addresses that require signatures appear at the beginning of the account
address array, with addresses requesting write access first and read-only address array, with addresses requesting read-write access first, and read-only
accounts following. The addresses that do not require signatures follow the accounts following. The addresses that do not require signatures follow the
addresses that do, again with read-write accounts first and read-only accounts addresses that do, again with read-write accounts first and read-only accounts
following. following.
@ -130,7 +130,7 @@ https://github.com/solana-labs/solana/blob/6606590b8132e56dab9e60b3f7d20ba7412a7
The instruction's [program id](terminology.md#program-id) specifies which The instruction's [program id](terminology.md#program-id) specifies which
program will process this instruction. The program's account's owner specifies program will process this instruction. The program's account's owner specifies
which loader should be used to load and execute the program and the data which loader should be used to load and execute the program, and the data
contains information about how the runtime should execute the program. contains information about how the runtime should execute the program.
In the case of [on-chain BPF programs](developing/on-chain-programs/overview.md), In the case of [on-chain BPF programs](developing/on-chain-programs/overview.md),
@ -145,7 +145,7 @@ are handled differently in that they are built directly into the Solana runtime.
### Accounts ### Accounts
The accounts referenced by an instruction represent on-chain state and serve as The accounts referenced by an instruction represent on-chain state and serve as
both the inputs and outputs of a program. More information about Accounts can be both the inputs and outputs of a program. More information about accounts can be
found in the [Accounts](accounts.md) section. found in the [Accounts](accounts.md) section.
### Instruction data ### Instruction data
@ -157,8 +157,8 @@ perform, and any additional information those operations may need above and
beyond what the accounts contain. beyond what the accounts contain.
Programs are free to specify how information is encoded into the instruction Programs are free to specify how information is encoded into the instruction
data byte array. The choice of how data is encoded should take into account the data byte array. The choice of how data is encoded should take into calculate the
overhead of decoding since that step is performed by the program on-chain. It's overhead of decoding, since that step is performed by the program on-chain. It's
been observed that some common encodings (Rust's bincode for example) are very been observed that some common encodings (Rust's bincode for example) are very
inefficient. inefficient.