Clarify runtime vs program rules (#5934)
* Clarify runtime vs program rules And define "smart contract" * Apply review feedback * Rename secret key to private key * Rename pubkey to public key in book "pubkey" is a great shorthand in code, but it's not common in the industry or something we want to spend time explaining to users.
This commit is contained in:
Greg Fitzgerald
GitHub
parent
c48c9be913
commit
badcb8b0e3
|
|
@ -80,7 +80,7 @@ $ solana pay <PUBKEY> 123 \
|
|||
// Return
|
||||
{signature: <TX_SIGNATURE>, processId: <PROCESS_ID>}
|
||||
```
|
||||
*`require-timestamp-from` is optional. If not provided, the transaction will expect a timestamp signed by this wallet's secret key*
|
||||
*`require-timestamp-from` is optional. If not provided, the transaction will expect a timestamp signed by this wallet's private key*
|
||||
|
||||
#### Authorized Transfer
|
||||
|
||||
|
|
@ -630,7 +630,7 @@ OPTIONS:
|
|||
--require-signature-from <PUBKEY>... Any third party signatures required to unlock the lamports
|
||||
|
||||
ARGS:
|
||||
<PUBKEY> The pubkey of recipient
|
||||
<PUBKEY> The public key of recipient
|
||||
<AMOUNT> The amount to send (default unit SOL)
|
||||
<unit> Specify unit to use for request [possible values: SOL, lamports]
|
||||
```
|
||||
|
|
@ -694,7 +694,7 @@ OPTIONS:
|
|||
-k, --keypair <PATH> /path/to/id.json
|
||||
|
||||
ARGS:
|
||||
<PUBKEY> The pubkey of recipient
|
||||
<PUBKEY> The public key of recipient
|
||||
<PROCESS ID> The process id of the transfer to authorize
|
||||
```
|
||||
|
||||
|
|
@ -716,7 +716,7 @@ OPTIONS:
|
|||
-k, --keypair <PATH> /path/to/id.json
|
||||
|
||||
ARGS:
|
||||
<PUBKEY> The pubkey of recipient
|
||||
<PUBKEY> The public key of recipient
|
||||
<PROCESS ID> The process id of the transfer to unlock
|
||||
```
|
||||
|
||||
|
|
@ -756,7 +756,7 @@ OPTIONS:
|
|||
-o, --output <FILE> Write the account data to this file
|
||||
|
||||
ARGS:
|
||||
<ACCOUNT PUBKEY> Account pubkey
|
||||
<ACCOUNT PUBKEY> Account public key
|
||||
```
|
||||
|
||||
```manpage
|
||||
|
|
@ -776,7 +776,7 @@ OPTIONS:
|
|||
-k, --keypair <PATH> /path/to/id.json
|
||||
|
||||
ARGS:
|
||||
<STAKE ACCOUNT PUBKEY> Stake account pubkey
|
||||
<STAKE ACCOUNT PUBKEY> Stake account public key
|
||||
```
|
||||
|
||||
```manpage
|
||||
|
|
@ -796,7 +796,7 @@ OPTIONS:
|
|||
-k, --keypair <PATH> /path/to/id.json
|
||||
|
||||
ARGS:
|
||||
<STORAGE ACCOUNT PUBKEY> Storage account pubkey
|
||||
<STORAGE ACCOUNT PUBKEY> Storage account public key
|
||||
```
|
||||
|
||||
```manpage
|
||||
|
|
@ -816,7 +816,7 @@ OPTIONS:
|
|||
-k, --keypair <PATH> /path/to/id.json
|
||||
|
||||
ARGS:
|
||||
<VOTE ACCOUNT PUBKEY> Vote account pubkey
|
||||
<VOTE ACCOUNT PUBKEY> Vote account public key
|
||||
```
|
||||
|
||||
```manpage
|
||||
|
|
|
|||
|
|
@ -13,7 +13,7 @@ buggy and malicious nodes.
|
|||
|
||||
Before starting any fullnodes, one first needs to create a *genesis block*.
|
||||
The block contains entries referencing two public keys, a *mint* and a
|
||||
*bootstrap leader*. The fullnode holding the bootstrap leader's secret key is
|
||||
*bootstrap leader*. The fullnode holding the bootstrap leader's private key is
|
||||
responsible for appending the first entries to the ledger. It initializes its
|
||||
internal state with the mint's account. That account will hold the number of
|
||||
native tokens defined by the genesis block. The second fullnode then contacts
|
||||
|
|
|
|||
|
|
@ -48,18 +48,30 @@ read its data and credit the account.
|
|||
|
||||
In the same way that a Linux user uses a path to look up a file, a Solana
|
||||
client uses public keys to look up accounts. To create an account, the client
|
||||
generates a *keypair* and registers its public key using the CreateAccount
|
||||
instruction. Once registered, transactions reference account keys to grant
|
||||
programs access to accounts. The runtime grants programs read access by
|
||||
default. To grant write access, the client must either assign the account to a
|
||||
program or sign the transaction using the keypair's *secret key*. Since only
|
||||
the holder of the secret key can produce valid signatures matching the
|
||||
account's public key, the runtime recognizes the signature as authorization to
|
||||
modify account data or debit the account.
|
||||
generates a *keypair* and registers its public key using the `CreateAccount`
|
||||
instruction. The account created by `CreateAccount` is called a *system
|
||||
account* and is owned by a built-in program called the System program. The
|
||||
System program allows clients to transfer lamports and assign account
|
||||
ownership.
|
||||
|
||||
The runtime only permits the owner to debit the account or modify its data. The
|
||||
program then defines additional rules for whether the client can modify
|
||||
accounts it owns. In the case of the System program, it allows users to
|
||||
transfer lamports by recognizing transaction signatures. If it sees the client
|
||||
signed the transaction using the keypair's *private key*, it knows the client
|
||||
authorized the token transfer.
|
||||
|
||||
After the runtime executes each of the transaction's instructions, it uses the
|
||||
account metadata and transaction signatures to verify that none of the access
|
||||
rules were violated. If a program violates an access rule, the runtime discards
|
||||
all account changes made by all instructions and marks the transaction as
|
||||
failed.
|
||||
account metadata to verify that none of the access rules were violated. If a
|
||||
program violates an access rule, the runtime discards all account changes made
|
||||
by all instructions and marks the transaction as failed.
|
||||
|
||||
## Smart Contracts
|
||||
|
||||
Programs don't always require transaction signatures, as the System program
|
||||
does. Instead, the program may manage *smart contracts*. A smart contract is a
|
||||
set of constraints that once satisfied, signal to a program that a token
|
||||
transfer or account update is permitted. For example, one could use the Budget
|
||||
program to create a smart contract that authorizes a token transfer only after
|
||||
some date. Once evidence that the date has past, the contract progresses, and
|
||||
token transfer completes.
|
||||
|
|
|
|||
|
|
@ -136,7 +136,7 @@ in a [transaction](#instruction).
|
|||
|
||||
#### keypair
|
||||
|
||||
A [public key](#public-key) and corresponding [secret key](#secret-key).
|
||||
A [public key](#public-key) and corresponding [private key](#private-key).
|
||||
|
||||
#### lamport
|
||||
|
||||
|
|
@ -208,6 +208,10 @@ See [Proof of History](#proof-of-history).
|
|||
|
||||
A weighted [credit](#credit) in a rewards regime. In the validator [rewards regime](staking-rewards.md), the number of points owed to a stake during redemption is the product of the [vote credits](#vote-credit) earned and the number of lamports staked.
|
||||
|
||||
#### private key
|
||||
|
||||
The private key of a [keypair](#keypair).
|
||||
|
||||
#### program
|
||||
|
||||
The code that interprets [instructions](#instruction).
|
||||
|
|
@ -246,15 +250,16 @@ excluded from consideration for consensus and can be discarded.
|
|||
The component of a [fullnode](#fullnode) responsible for [program](#program)
|
||||
execution.
|
||||
|
||||
#### secret key
|
||||
|
||||
The private key of a [keypair](#keypair).
|
||||
|
||||
#### slot
|
||||
|
||||
The period of time for which a [leader](#leader) ingests transactions and
|
||||
produces a [block](#block).
|
||||
|
||||
#### smart contract
|
||||
|
||||
A set of constraints that once satisfied, signal to a program that some
|
||||
predefined account updates are permitted.
|
||||
|
||||
#### sol
|
||||
|
||||
The [native token](#native-token) tracked by a [cluster](#cluster) recognized
|
||||
|
|
|
|||
|
|
@ -14,11 +14,11 @@
|
|||
by multiple parallel transactions, but their balance may only be
|
||||
increased, and their account data is read-only.
|
||||
* **num_credit_only_unsigned_accounts:** The last
|
||||
`num_credit_only_unsigned_accounts` pubkeys in `account_keys` refer
|
||||
`num_credit_only_unsigned_accounts` public keys in `account_keys` refer
|
||||
to non-signing credit only accounts
|
||||
* **account_keys:** List of pubkeys used by the transaction, including
|
||||
* **account_keys:** List of public keys used by the transaction, including
|
||||
by the instructions and for signatures. The first
|
||||
`num_required_signatures` pubkeys must sign the transaction.
|
||||
`num_required_signatures` public keys must sign the transaction.
|
||||
* **recent_blockhash:** The ID of a recent ledger entry. Validators will
|
||||
reject transactions with a `recent_blockhash` that is too old.
|
||||
* **instructions:** A list of [instructions](instruction.md) that are
|
||||
|
|
@ -26,7 +26,7 @@
|
|||
succeed.
|
||||
* **signatures:** A list of signatures applied to the transaction. The
|
||||
list is always of length `num_required_signatures`, and the signature
|
||||
at index `i` corresponds to the pubkey at index `i` in `account_keys`.
|
||||
at index `i` corresponds to the public key at index `i` in `account_keys`.
|
||||
The list is initialized with empty signatures (i.e. zeros), and
|
||||
populated as signatures are added.
|
||||
|
||||
|
|
@ -34,7 +34,7 @@
|
|||
|
||||
A `Transaction` is signed by using an ed25519 keypair to sign the
|
||||
serialization of the `message`. The resulting signature is placed at the
|
||||
index of `signatures` matching the index of the keypair's pubkey in
|
||||
index of `signatures` matching the index of the keypair's public key in
|
||||
`account_keys`.
|
||||
|
||||
### Transaction Serialization
|
||||
|
|
@ -45,4 +45,4 @@ non-standard vector serialization that uses only one byte for the length
|
|||
if it can be encoded in 7 bits, 2 bytes if it fits in 14 bits, or 3
|
||||
bytes if it requires 15 or 16 bits. The vector serialization is defined
|
||||
by Solana's
|
||||
[short-vec](https://github.com/solana-labs/solana/blob/master/sdk/src/short_vec.rs).
|
||||
[short-vec](https://github.com/solana-labs/solana/blob/master/sdk/src/short_vec.rs).
|
||||
|
|
|
|||
|
|
@ -2,26 +2,24 @@
|
|||
|
||||
Transactions encode lists of instructions that are executed
|
||||
sequentially, and only committed if all the instructions complete
|
||||
successfully. All account states are reverted upon the failure of a
|
||||
transaction. Each Transaction details the accounts used, including which
|
||||
successfully. All account updates are reverted upon the failure of a
|
||||
transaction. Each transaction details the accounts used, including which
|
||||
must sign and which are credit only, a recent blockhash, the
|
||||
instructions, and any signatures.
|
||||
|
||||
## Accounts and Signatures
|
||||
|
||||
Each transaction explicitly lists all accounts that it needs access to.
|
||||
This includes accounts that are transferring tokens, accounts whose user
|
||||
data is being modified, and the program accounts that are being called
|
||||
by the instructions. Each account that is not an executable program can
|
||||
be marked as a requiring a signature and/or as credit only. All accounts
|
||||
marked as signers must have a valid signature in the transaction's list
|
||||
of signatures before the transaction is considered valid. Any accounts
|
||||
marked as credit only may only have their token value increased, and
|
||||
their user data is read only. Accounts are locked by the runtime,
|
||||
ensuring that they are not modified by a concurrent program while the
|
||||
transaction is running. Credit only accounts can safely be shared, so
|
||||
the runtime will allow multiple concurrent credit only locks on an
|
||||
account.
|
||||
Each transaction explicitly lists all account public keys referenced by the
|
||||
transaction's instructions. A subset of those public keys are each accompanied
|
||||
by a transaction signature. Those signatures signal on-chain programs that
|
||||
the account holder has authorized the transaction. Typically, the program
|
||||
uses the authorization to permit debiting the account or modifying its
|
||||
data.
|
||||
|
||||
The transaction also marks some accounts as *credit-only accounts*. The
|
||||
runtime permits credit-only accounts to be credited concurrently. If a
|
||||
program attempts to debit a credit-only account or modify its account
|
||||
data, the transaction is rejected by the runtime.
|
||||
|
||||
## Recent Blockhash
|
||||
|
||||
|
|
@ -40,4 +38,4 @@ be passed to the program, and a data byte array instruction that is
|
|||
passed to the program. The program interprets the data array and
|
||||
operates on the accounts specified by the instructions. The program can
|
||||
return successfully, or with an error code. An error return causes the
|
||||
entire transaction to fail immediately.
|
||||
entire transaction to fail immediately.
|
||||
|
|
|
|||
Loading…
Reference in New Issue