diff --git a/docs/src/apps/jsonrpc-api.md b/docs/src/apps/jsonrpc-api.md index 23a887637d..4f6bd7ece7 100644 --- a/docs/src/apps/jsonrpc-api.md +++ b/docs/src/apps/jsonrpc-api.md @@ -891,7 +891,7 @@ The result field will be a JSON object of `current` and `delinquent` accounts, e * `epochVoteAccount: ` - bool, whether the vote account is staked for this epoch * `commission: `, percentage (0-100) of rewards payout owed to the vote account * `lastVote: ` - Most recent slot voted on by this vote account -* `epochCredits: ` - History of how many credits earned by the end of each epoch, as an array of arrays containing: [epoch, credits, previousCredits] +* `epochCredits: ` - History of how many credits earned by the end of each epoch, as an array of arrays containing: `[epoch, credits, previousCredits]` #### Example: diff --git a/docs/src/cli/generate-keys.md b/docs/src/cli/generate-keys.md index 83b588824a..b47ec1ba45 100644 --- a/docs/src/cli/generate-keys.md +++ b/docs/src/cli/generate-keys.md @@ -69,7 +69,7 @@ keypair generated from your seed phrase, and "Failed" otherwise. ## Generate a Hardware Wallet Keypair Keypairs are automatically derived when you query a hardware wallet with a -[keypair URL](../remote-wallet#specify-a-hardware-wallet-key). +[keypair URL](../remote-wallet/README.md#specify-a-hardware-wallet-key). Once you have your keypair URL, use `solana-keygen pubkey` to query the hardware wallet for the keypair's public key: diff --git a/docs/src/implemented-proposals/ed_overview/README.md b/docs/src/implemented-proposals/ed_overview/README.md index 93407730e8..165c2403c3 100644 --- a/docs/src/implemented-proposals/ed_overview/README.md +++ b/docs/src/implemented-proposals/ed_overview/README.md @@ -10,7 +10,7 @@ These protocol-based rewards, to be distributed to participating validation and Transaction fees are market-based participant-to-participant transfers, attached to network interactions as a necessary motivation and compensation for the inclusion and execution of a proposed transaction \(be it a state execution or proof-of-replication verification\). A mechanism for long-term economic stability and forking protection through partial burning of each transaction fee is also discussed below. -A high-level schematic of Solana’s crypto-economic design is shown below in **Figure 1**. The specifics of validation-client economics are described in sections: [Validation-client Economics](ed_validation_client_economics/), [State-validation Protocol-based Rewards](ed_validation_client_economics/ed_vce_state_validation_protocol_based_rewards.md), [State-validation Transaction Fees](ed_validation_client_economics/ed_vce_state_validation_transaction_fees.md) and [Replication-validation Transaction Fees](ed_validation_client_economics/ed_vce_replication_validation_transaction_fees.md). Also, the section titled [Validation Stake Delegation](ed_validation_client_economics/ed_vce_validation_stake_delegation.md) closes with a discussion of validator delegation opportunities and marketplace. Additionally, in [Storage Rent Economics](ed_storage_rent_economics.md), we describe an implementation of storage rent to account for the externality costs of maintaining the active state of the ledger. [Replication-client Economics](ed_replication_client_economics/) will review the Solana network design for global ledger storage/redundancy and archiver-client economics \([Storage-replication rewards](ed_replication_client_economics/ed_rce_storage_replication_rewards.md)\) along with an archiver-to-validator delegation mechanism designed to aide participant on-boarding into the Solana economy discussed in [Replication-client Reward Auto-delegation](ed_replication_client_economics/ed_rce_replication_client_reward_auto_delegation.md). An outline of features for an MVP economic design is discussed in the [Economic Design MVP](ed_mvp.md) section. Finally, in [Attack Vectors](ed_attack_vectors.md), various attack vectors will be described and potential vulnerabilities explored and parameterized. +A high-level schematic of Solana’s crypto-economic design is shown below in **Figure 1**. The specifics of validation-client economics are described in sections: [Validation-client Economics](ed_validation_client_economics/README.md), [State-validation Protocol-based Rewards](ed_validation_client_economics/ed_vce_state_validation_protocol_based_rewards.md), [State-validation Transaction Fees](ed_validation_client_economics/ed_vce_state_validation_transaction_fees.md) and [Replication-validation Transaction Fees](ed_validation_client_economics/ed_vce_replication_validation_transaction_fees.md). Also, the section titled [Validation Stake Delegation](ed_validation_client_economics/ed_vce_validation_stake_delegation.md) closes with a discussion of validator delegation opportunities and marketplace. Additionally, in [Storage Rent Economics](ed_storage_rent_economics.md), we describe an implementation of storage rent to account for the externality costs of maintaining the active state of the ledger. [Replication-client Economics](ed_replication_client_economics/README.md) will review the Solana network design for global ledger storage/redundancy and archiver-client economics \([Storage-replication rewards](ed_replication_client_economics/ed_rce_storage_replication_rewards.md)\) along with an archiver-to-validator delegation mechanism designed to aide participant on-boarding into the Solana economy discussed in [Replication-client Reward Auto-delegation](ed_replication_client_economics/ed_rce_replication_client_reward_auto_delegation.md). An outline of features for an MVP economic design is discussed in the [Economic Design MVP](ed_mvp.md) section. Finally, in [Attack Vectors](ed_attack_vectors.md), various attack vectors will be described and potential vulnerabilities explored and parameterized. ![](../../.gitbook/assets/economic_design_infl_230719.png) diff --git a/docs/src/implemented-proposals/ed_overview/ed_mvp.md b/docs/src/implemented-proposals/ed_overview/ed_mvp.md index a525cc9838..77fb33e301 100644 --- a/docs/src/implemented-proposals/ed_overview/ed_mvp.md +++ b/docs/src/implemented-proposals/ed_overview/ed_mvp.md @@ -2,7 +2,7 @@ **Subject to change.** -The preceding sections, outlined in the [Economic Design Overview](./), describe a long-term vision of a sustainable Solana economy. Of course, we don't expect the final implementation to perfectly match what has been described above. We intend to fully engage with network stakeholders throughout the implementation phases \(i.e. pre-testnet, testnet, mainnet\) to ensure the system supports, and is representative of, the various network participants' interests. The first step toward this goal, however, is outlining a some desired MVP economic features to be available for early pre-testnet and testnet participants. Below is a rough sketch outlining basic economic functionality from which a more complete and functional system can be developed. +The preceding sections, outlined in the [Economic Design Overview](../README.md), describe a long-term vision of a sustainable Solana economy. Of course, we don't expect the final implementation to perfectly match what has been described above. We intend to fully engage with network stakeholders throughout the implementation phases \(i.e. pre-testnet, testnet, mainnet\) to ensure the system supports, and is representative of, the various network participants' interests. The first step toward this goal, however, is outlining a some desired MVP economic features to be available for early pre-testnet and testnet participants. Below is a rough sketch outlining basic economic functionality from which a more complete and functional system can be developed. ## MVP Economic Features diff --git a/docs/src/implemented-proposals/ed_overview/ed_validation_client_economics/ed_vce_state_validation_protocol_based_rewards.md b/docs/src/implemented-proposals/ed_overview/ed_validation_client_economics/ed_vce_state_validation_protocol_based_rewards.md index b213a812ac..34c6fa5f05 100644 --- a/docs/src/implemented-proposals/ed_overview/ed_validation_client_economics/ed_vce_state_validation_protocol_based_rewards.md +++ b/docs/src/implemented-proposals/ed_overview/ed_validation_client_economics/ed_vce_state_validation_protocol_based_rewards.md @@ -4,7 +4,7 @@ Validator-clients have two functional roles in the Solana network: -* Validate \(vote\) the current global state of that PoH along with any Proofs-of-Replication \(see [Replication Client Economics](../ed_replication_client_economics/)\) that they are eligible to validate. +* Validate \(vote\) the current global state of that PoH along with any Proofs-of-Replication \(see [Replication Client Economics](../ed_replication_client_economics/README.md)\) that they are eligible to validate. * Be elected as ‘leader’ on a stake-weighted round-robin schedule during which time they are responsible for collecting outstanding transactions and Proofs-of-Replication and incorporating them into the PoH, thus updating the global state of the network and providing chain continuity. Validator-client rewards for these services are to be distributed at the end of each Solana epoch. As previously discussed, compensation for validator-clients is provided via a protocol-based annual inflation rate dispersed in proportion to the stake-weight of each validator \(see below\) along with leader-claimed transaction fees available during each leader rotation. I.e. during the time a given validator-client is elected as leader, it has the opportunity to keep a portion of each transaction fee, less a protocol-specified amount that is destroyed \(see [Validation-client State Transaction Fees](ed_vce_state_validation_transaction_fees.md)\). PoRep transaction fees are also collected by the leader client and validator PoRep rewards are distributed in proportion to the number of validated PoReps less the number of PoReps that mismatch an archiver's challenge. \(see [Replication-client Transaction Fees](ed_vce_replication_validation_transaction_fees.md)\) diff --git a/docs/src/implemented-proposals/ed_overview/ed_validation_client_economics/ed_vce_validation_stake_delegation.md b/docs/src/implemented-proposals/ed_overview/ed_validation_client_economics/ed_vce_validation_stake_delegation.md index 8f05d81a76..9490875102 100644 --- a/docs/src/implemented-proposals/ed_overview/ed_validation_client_economics/ed_vce_validation_stake_delegation.md +++ b/docs/src/implemented-proposals/ed_overview/ed_validation_client_economics/ed_vce_validation_stake_delegation.md @@ -24,7 +24,7 @@ Running a Solana validation-client required relatively modest upfront hardware c Despite the low-barrier to entry as a validation-client, from a capital investment perspective, as in any developing economy, there will be much opportunity and need for trusted validation services as evidenced by node reliability, UX/UI, APIs and other software accessibility tools. Additionally, although Solana’s validator node startup costs are nominal when compared to similar networks, they may still be somewhat restrictive for some potential participants. In the spirit of developing a true decentralized, permissionless network, these interested parties still have two options to become involved in the Solana network/economy: 1. Delegation of previously acquired tokens with a reliable validation node to earn a portion of interest generated -2. Provide local storage space as a replication-client and receive rewards by submitting Proof-of-Replication \(see [Replication-client Economics](../ed_replication_client_economics/)\). +2. Provide local storage space as a replication-client and receive rewards by submitting Proof-of-Replication \(see [Replication-client Economics](../ed_replication_client_economics/README.md)\). a. This participant has the additional option to directly delegate their earned storage rewards \([Replication-client Reward Auto-delegation](../ed_replication_client_economics/ed_rce_replication_client_reward_auto_delegation.md)\) diff --git a/docs/src/implemented-proposals/leader-validator-transition.md b/docs/src/implemented-proposals/leader-validator-transition.md index edae58bec0..49a9641c02 100644 --- a/docs/src/implemented-proposals/leader-validator-transition.md +++ b/docs/src/implemented-proposals/leader-validator-transition.md @@ -20,7 +20,7 @@ Slot leaders and validators use a PoH Recorder for both estimating slot height a ### PoH Recorder when Validating -The PoH Recorder acts as a simple VDF when validating. It tells the validator when it needs to switch to the slot leader role. Every time the validator votes on a fork, it should use the fork's latest [blockhash](terminology.md#blockhash) to re-seed the VDF. Re-seeding solves two problems. First, it synchronizes its VDF to the leader's, allowing it to more accurately determine when its leader slot begins. Second, if the previous leader goes down, all wallclock time is accounted for in the next leader's PoH stream. For example, if one block is missing when the leader starts, the block it produces should have a PoH duration of two blocks. The longer duration ensures the following leader isn't attempting to snip all the transactions from the previous leader's slot. +The PoH Recorder acts as a simple VDF when validating. It tells the validator when it needs to switch to the slot leader role. Every time the validator votes on a fork, it should use the fork's latest [blockhash](../terminology.md#blockhash) to re-seed the VDF. Re-seeding solves two problems. First, it synchronizes its VDF to the leader's, allowing it to more accurately determine when its leader slot begins. Second, if the previous leader goes down, all wallclock time is accounted for in the next leader's PoH stream. For example, if one block is missing when the leader starts, the block it produces should have a PoH duration of two blocks. The longer duration ensures the following leader isn't attempting to snip all the transactions from the previous leader's slot. ### PoH Recorder when Leading diff --git a/docs/src/implemented-proposals/staking-rewards.md b/docs/src/implemented-proposals/staking-rewards.md index 3efa341bda..82aa7c3d9f 100644 --- a/docs/src/implemented-proposals/staking-rewards.md +++ b/docs/src/implemented-proposals/staking-rewards.md @@ -50,7 +50,7 @@ Solana's trustless sense of time and ordering provided by its PoH data structure ## Penalties -As discussed in the [Economic Design](../implemented-proposals/ed_overview/) section, annual validator interest rates are to be specified as a function of total percentage of circulating supply that has been staked. The cluster rewards validators who are online and actively participating in the validation process throughout the entirety of their _validation period_. For validators that go offline/fail to validate transactions during this period, their annual reward is effectively reduced. +As discussed in the [Economic Design](../implemented-proposals/ed_overview/README.md) section, annual validator interest rates are to be specified as a function of total percentage of circulating supply that has been staked. The cluster rewards validators who are online and actively participating in the validation process throughout the entirety of their _validation period_. For validators that go offline/fail to validate transactions during this period, their annual reward is effectively reduced. Similarly, we may consider an algorithmic reduction in a validator's active amount staked amount in the case that they are offline. I.e. if a validator is inactive for some amount of time, either due to a partition or otherwise, the amount of their stake that is considered ‘active’ \(eligible to earn rewards\) may be reduced. This design would be structured to help long-lived partitions to eventually reach finality on their respective chains as the % of non-voting total stake is reduced over time until a supermajority can be achieved by the active validators in each partition. Similarly, upon re-engaging, the ‘active’ amount staked will come back online at some defined rate. Different rates of stake reduction may be considered depending on the size of the partition/active set. diff --git a/docs/src/offline-signing/README.md b/docs/src/offline-signing/README.md index e5a78f86fa..4e697ad981 100644 --- a/docs/src/offline-signing/README.md +++ b/docs/src/offline-signing/README.md @@ -4,7 +4,7 @@ Some security models require keeping signing keys, and thus the signing process, separated from transaction creation and network broadcast. Examples include: * Collecting signatures from geographically disparate signers in a -[multi-signature scheme](../api-reference/cli.md#multiple-witnesses) +[multi-signature scheme](../cli/usage.md#multiple-witnesses) * Signing transactions using an [airgapped](https://en.wikipedia.org/wiki/Air_gap_(networking)) signing device diff --git a/docs/src/offline-signing/durable-nonce.md b/docs/src/offline-signing/durable-nonce.md index 1af9b5b8d8..a53ecbf5f5 100644 --- a/docs/src/offline-signing/durable-nonce.md +++ b/docs/src/offline-signing/durable-nonce.md @@ -8,7 +8,7 @@ about in the [proposal](../implemented-proposals/durable-tx-nonces.md). ## Usage Examples Full usage details for durable nonce CLI commands can be found in the -[CLI reference](../api-reference/cli.md). +[CLI reference](../cli/usage.md). ### Nonce Authority @@ -52,7 +52,7 @@ instead {% endhint %} {% hint style="info" %} -[Full usage documentation](../api-reference/cli.md#solana-create-nonce-account) +[Full usage documentation](../cli/usage.md#solana-create-nonce-account) {% endhint %} ### Querying the Stored Nonce Value @@ -74,7 +74,7 @@ solana nonce nonce-keypair.json ``` {% hint style="info" %} -[Full usage documentation](../api-reference/cli.md#solana-get-nonce) +[Full usage documentation](../cli/usage.md#solana-get-nonce) {% endhint %} ### Advancing the Stored Nonce Value @@ -95,7 +95,7 @@ solana new-nonce nonce-keypair.json ``` {% hint style="info" %} -[Full usage documentation](../api-reference/cli.md#solana-new-nonce) +[Full usage documentation](../cli/usage.md#solana-new-nonce) {% endhint %} ### Display Nonce Account @@ -117,7 +117,7 @@ nonce: DZar6t2EaCFQTbUP4DHKwZ1wT8gCPW2aRfkVWhydkBvS ``` {% hint style="info" %} -[Full usage documentation](../api-reference/cli.md#solana-nonce-account) +[Full usage documentation](../cli/usage.md#solana-nonce-account) {% endhint %} ### Withdraw Funds from a Nonce Account @@ -141,7 +141,7 @@ Close a nonce account by withdrawing the full balance {% endhint %} {% hint style="info" %} -[Full usage documentation](../api-reference/cli.md#solana-withdraw-from-nonce-account) +[Full usage documentation](../cli/usage.md#solana-withdraw-from-nonce-account) {% endhint %} ### Assign a New Authority to a Nonce Account @@ -161,7 +161,7 @@ solana authorize-nonce-account nonce-keypair.json nonce-authority.json ``` {% hint style="info" %} -[Full usage documentation](../api-reference/cli.md#solana-authorize-nonce-account) +[Full usage documentation](../cli/usage.md#solana-authorize-nonce-account) {% endhint %} ## Other Commands Supporting Durable Nonces @@ -172,9 +172,9 @@ supported. * `--nonce-authority`, specifies an optional [nonce authority](#nonce-authority) The following subcommands have received this treatment so far -* [`pay`](../api-reference/cli.md#solana-pay) -* [`delegate-stake`](../api-reference/cli.md#solana-delegate-stake) -* [`deactivate-stake`](../api-reference/cli.md#solana-deactivate-stake) +* [`pay`](../cli/usage.md#solana-pay) +* [`delegate-stake`](../cli/usage.md#solana-delegate-stake) +* [`deactivate-stake`](../cli/usage.md#solana-deactivate-stake) ### Example Pay Using Durable Nonce diff --git a/docs/src/proposals/abi-management.md b/docs/src/proposals/abi-management.md index 0e802e5508..61f04934b1 100644 --- a/docs/src/proposals/abi-management.md +++ b/docs/src/proposals/abi-management.md @@ -80,8 +80,8 @@ hard forks should be approached. We use some degree of macro machinery to automatically generate unit tests and calculate a digest from ABI items. This is doable by clever use of -`serde::Serialize` ([1]) and `any::typename` ([2]). For a precedent for similar -implementation, `ink` from the Parity Technologies [3] could be informational. +`serde::Serialize` (`[1]`) and `any::typename` (`[2]`). For a precedent for similar +implementation, `ink` from the Parity Technologies `[3]` could be informational. # References diff --git a/docs/src/remote-wallet/ledger.md b/docs/src/remote-wallet/ledger.md index 1321865b65..c28e90b115 100644 --- a/docs/src/remote-wallet/ledger.md +++ b/docs/src/remote-wallet/ledger.md @@ -51,8 +51,8 @@ Confirm it prints the same wallet ID as before. To learn more about keypair URLs, see [Specify A Hardware Wallet Key](README.md#specify-a-hardware-wallet-key) -Read more about [sending and receiving tokens](../transfer-tokens.md) and -[delegating stake](../delegate-stake.md). You can use your Ledger keypair URL +Read more about [sending and receiving tokens](../cli/transfer-tokens.md) and +[delegating stake](../cli/delegate-stake.md). You can use your Ledger keypair URL anywhere you see an option or argument that accepts a ``. ## Support diff --git a/docs/src/running-validator/validator-stake.md b/docs/src/running-validator/validator-stake.md index eec32086b8..1b1acac1a3 100644 --- a/docs/src/running-validator/validator-stake.md +++ b/docs/src/running-validator/validator-stake.md @@ -69,7 +69,7 @@ account. This is a normal transaction so the standard transaction fee will apply. The transaction fee range is defined by the genesis block. The actual fee will fluctuate based on transaction load. You can determine the current fee via the -[RPC API “getRecentBlockhash”](../api-reference/jsonrpc-api.md#getrecentblockhash) +[RPC API “getRecentBlockhash”](../apps/jsonrpc-api.md#getrecentblockhash) before submitting a transaction. Learn more about [transaction fees here](../implemented-proposals/transaction-fees.md). diff --git a/docs/src/terminology.md b/docs/src/terminology.md index f6486c6f20..1f9ecccd45 100644 --- a/docs/src/terminology.md +++ b/docs/src/terminology.md @@ -56,7 +56,7 @@ A gossip network connecting all [nodes](terminology.md#node) of a [cluster](term ## cooldown period -Some number of epochs after stake has been deactivated while it progressively becomes available for withdrawal. During this period, the stake is considered to be "deactivating". More info about: [warmup and cooldown](cluster/stake-delegation-and-rewards.md#stake-warmup-cooldown-withdrawal) +Some number of epochs after stake has been deactivated while it progressively becomes available for withdrawal. During this period, the stake is considered to be "deactivating". More info about: [warmup and cooldown](implemented-proposals/staking-rewards.md#stake-warmup-cooldown-withdrawal) ## credit @@ -182,7 +182,7 @@ See [Proof of History](terminology.md#proof-of-history). ## point -A weighted [credit](terminology.md#credit) in a rewards regime. In the validator [rewards regime](proposals/staking-rewards.md), the number of points owed to a stake during redemption is the product of the [vote credits](terminology.md#vote-credit) earned and the number of lamports staked. +A weighted [credit](terminology.md#credit) in a rewards regime. In the validator [rewards regime](cluster/stake-delegation-and-rewards.md), the number of points owed to a stake during redemption is the product of the [vote credits](terminology.md#vote-credit) earned and the number of lamports staked. ## private key diff --git a/docs/src/tour-de-sol/participation/steps-to-create-a-validator/validator-public-key-registration.md b/docs/src/tour-de-sol/participation/steps-to-create-a-validator/validator-public-key-registration.md index 8b2ca1d9ff..a5db2cdf86 100644 --- a/docs/src/tour-de-sol/participation/steps-to-create-a-validator/validator-public-key-registration.md +++ b/docs/src/tour-de-sol/participation/steps-to-create-a-validator/validator-public-key-registration.md @@ -2,7 +2,7 @@ In order to participate in any Tour de SOL dry-runs or stages, you need to register for the Tour de SOL. -See [Registration info](../../registration/). +See [Registration info](../../registration/README.md). In order to obtain your allotment of lamports at the start of a Tour de SOL stage or dry run, you need to publish your validator's identity public key under your keybase.io account. diff --git a/docs/src/validator/blockstore.md b/docs/src/validator/blockstore.md index 722b87ff62..1c51648c47 100644 --- a/docs/src/validator/blockstore.md +++ b/docs/src/validator/blockstore.md @@ -1,6 +1,6 @@ # Blockstore -After a block reaches finality, all blocks from that one on down to the genesis block form a linear chain with the familiar name blockchain. Until that point, however, the validator must maintain all potentially valid chains, called _forks_. The process by which forks naturally form as a result of leader rotation is described in [fork generation](../../cluster/fork-generation.md). The _blockstore_ data structure described here is how a validator copes with those forks until blocks are finalized. +After a block reaches finality, all blocks from that one on down to the genesis block form a linear chain with the familiar name blockchain. Until that point, however, the validator must maintain all potentially valid chains, called _forks_. The process by which forks naturally form as a result of leader rotation is described in [fork generation](../cluster/fork-generation.md). The _blockstore_ data structure described here is how a validator copes with those forks until blocks are finalized. The blockstore allows a validator to record every shred it observes on the network, in any order, as long as the shred is signed by the expected leader for a given slot. diff --git a/docs/src/validator/runtime.md b/docs/src/validator/runtime.md index 9c0c96612f..2bc71f6ce9 100644 --- a/docs/src/validator/runtime.md +++ b/docs/src/validator/runtime.md @@ -64,4 +64,4 @@ To pass messages between programs, the receiving program must accept the message ## Future Work -* [Continuations and Signals for long running Transactions]([https://github.com/solana-labs/solana/issues/1485]) +* [Continuations and Signals for long running Transactions](https://github.com/solana-labs/solana/issues/1485) diff --git a/docs/src/wallet/cli-wallets.md b/docs/src/wallet/cli-wallets.md index 202f055e03..44ad767c87 100644 --- a/docs/src/wallet/cli-wallets.md +++ b/docs/src/wallet/cli-wallets.md @@ -40,7 +40,7 @@ In terms of convenience versus security, a paper wallet sits at the opposite side of the spectrum from an FS wallet. It is terribly inconvenient to use, but offers excellent security. That high security is further amplified when paper wallets are used in conjunction with -[offline signing](../offline-signing/index.md). Custody services such as +[offline signing](../offline-signing/README.md). Custody services such as [Coinbase Custody](https://custody.coinbase.com/) use this combination. Paper wallets and custody services are an excellent way to secure a large number of tokens for a long period of time.