solana-docs 0.0.0

package/src/clusters.md

@@ -0,0 +1,173 @@
+---
+title: Solana Clusters
+---
+
+Solana maintains several different clusters with different purposes.
+
+Before you begin make sure you have first
+[installed the Solana command line tools](cli/install-solana-cli-tools.md)
+
+Explorers:
+
+- [http://explorer.solana.com/](https://explorer.solana.com/).
+- [http://solanabeach.io/](http://solanabeach.io/).
+
+## Devnet
+
+- Devnet serves as a playground for anyone who wants to take Solana for a
+  test drive, as a user, token holder, app developer, or validator.
+- Application developers should target Devnet.
+- Potential validators should first target Devnet.
+- Key differences between Devnet and Mainnet Beta:
+  - Devnet tokens are **not real**
+  - Devnet includes a token faucet for airdrops for application testing
+  - Devnet may be subject to ledger resets
+  - Devnet typically runs a newer software version than Mainnet Beta
+- Gossip entrypoint for Devnet: `entrypoint.devnet.solana.com:8001`
+- Metrics environment variable for Devnet:
+
+```bash
+export SOLANA_METRICS_CONFIG="host=https://metrics.solana.com:8086,db=devnet,u=scratch_writer,p=topsecret"
+```
+
+- RPC URL for Devnet: `https://api.devnet.solana.com`
+
+##### Example `solana` command-line configuration
+
+```bash
+solana config set --url https://api.devnet.solana.com
+```
+
+##### Example `solana-validator` command-line
+
+```bash
+$ solana-validator \
+    --identity validator-keypair.json \
+    --vote-account vote-account-keypair.json \
+    --known-validator dv1ZAGvdsz5hHLwWXsVnM94hWf1pjbKVau1QVkaMJ92 \
+    --known-validator dv2eQHeP4RFrJZ6UeiZWoc3XTtmtZCUKxxCApCDcRNV \
+    --known-validator dv4ACNkpYPcE3aKmYDqZm9G5EB3J4MRoeE7WNDRBVJB \
+    --known-validator dv3qDFk1DTF36Z62bNvrCXe9sKATA6xvVy6A798xxAS \
+    --only-known-rpc \
+    --ledger ledger \
+    --rpc-port 8899 \
+    --dynamic-port-range 8000-8010 \
+    --entrypoint entrypoint.devnet.solana.com:8001 \
+    --entrypoint entrypoint2.devnet.solana.com:8001 \
+    --entrypoint entrypoint3.devnet.solana.com:8001 \
+    --entrypoint entrypoint4.devnet.solana.com:8001 \
+    --entrypoint entrypoint5.devnet.solana.com:8001 \
+    --expected-genesis-hash EtWTRABZaYq6iMfeYKouRu166VU2xqa1wcaWoxPkrZBG \
+    --wal-recovery-mode skip_any_corrupted_record \
+    --limit-ledger-size
+```
+
+The [`--known-validator`s](running-validator/validator-start.md#known-validators)
+are operated by Solana Labs
+
+## Testnet
+
+- Testnet is where we stress test recent release features on a live
+  cluster, particularly focused on network performance, stability and validator
+  behavior.
+- Testnet tokens are **not real**
+- Testnet may be subject to ledger resets.
+- Testnet includes a token faucet for airdrops for application testing
+- Testnet typically runs a newer software release than both Devnet and
+  Mainnet Beta
+- Gossip entrypoint for Testnet: `entrypoint.testnet.solana.com:8001`
+- Metrics environment variable for Testnet:
+
+```bash
+export SOLANA_METRICS_CONFIG="host=https://metrics.solana.com:8086,db=tds,u=testnet_write,p=c4fa841aa918bf8274e3e2a44d77568d9861b3ea"
+```
+
+- RPC URL for Testnet: `https://api.testnet.solana.com`
+
+##### Example `solana` command-line configuration
+
+```bash
+solana config set --url https://api.testnet.solana.com
+```
+
+##### Example `solana-validator` command-line
+
+```bash
+$ solana-validator \
+    --identity validator-keypair.json \
+    --vote-account vote-account-keypair.json \
+    --known-validator 5D1fNXzvv5NjV1ysLjirC4WY92RNsVH18vjmcszZd8on \
+    --known-validator 7XSY3MrYnK8vq693Rju17bbPkCN3Z7KvvfvJx4kdrsSY \
+    --known-validator Ft5fbkqNa76vnsjYNwjDZUXoTWpP7VYm3mtsaQckQADN \
+    --known-validator 9QxCLckBiJc783jnMvXZubK4wH86Eqqvashtrwvcsgkv \
+    --only-known-rpc \
+    --ledger ledger \
+    --rpc-port 8899 \
+    --dynamic-port-range 8000-8010 \
+    --entrypoint entrypoint.testnet.solana.com:8001 \
+    --entrypoint entrypoint2.testnet.solana.com:8001 \
+    --entrypoint entrypoint3.testnet.solana.com:8001 \
+    --expected-genesis-hash 4uhcVJyU9pJkvQyS88uRDiswHXSCkY3zQawwpjk2NsNY \
+    --wal-recovery-mode skip_any_corrupted_record \
+    --limit-ledger-size
+```
+
+The identities of the
+[`--known-validator`s](running-validator/validator-start.md#known-validators) are:
+
+- `5D1fNXzvv5NjV1ysLjirC4WY92RNsVH18vjmcszZd8on` - Solana Labs (testnet.solana.com)
+- `Ft5fbkqNa76vnsjYNwjDZUXoTWpP7VYm3mtsaQckQADN` - Certus One
+- `9QxCLckBiJc783jnMvXZubK4wH86Eqqvashtrwvcsgkv` - Algo|Stake
+
+## Mainnet Beta
+
+A permissionless, persistent cluster for early token holders and launch partners.
+
+- Tokens that are issued on Mainnet Beta are **real** SOL
+- If you have paid money to purchase/be issued tokens, such as through our
+  CoinList auction, these tokens will be transferred on Mainnet Beta.
+  - Note: If you are using a non-command-line wallet such as
+    [Solflare](wallet-guide/solflare.md),
+    the wallet will always be connecting to Mainnet Beta.
+- Gossip entrypoint for Mainnet Beta: `entrypoint.mainnet-beta.solana.com:8001`
+- Metrics environment variable for Mainnet Beta:
+
+```bash
+export SOLANA_METRICS_CONFIG="host=https://metrics.solana.com:8086,db=mainnet-beta,u=mainnet-beta_write,p=password"
+```
+
+- RPC URL for Mainnet Beta: `https://api.mainnet-beta.solana.com`
+
+##### Example `solana` command-line configuration
+
+```bash
+solana config set --url https://api.mainnet-beta.solana.com
+```
+
+##### Example `solana-validator` command-line
+
+```bash
+$ solana-validator \
+    --identity ~/validator-keypair.json \
+    --vote-account ~/vote-account-keypair.json \
+    --known-validator 7Np41oeYqPefeNQEHSv1UDhYrehxin3NStELsSKCT4K2 \
+    --known-validator GdnSyH3YtwcxFvQrVVJMm1JhTS4QVX7MFsX56uJLUfiZ \
+    --known-validator DE1bawNcRJB9rVm3buyMVfr8mBEoyyu73NBovf2oXJsJ \
+    --known-validator CakcnaRDHka2gXyfbEd2d3xsvkJkqsLw2akB3zsN1D2S \
+    --only-known-rpc \
+    --ledger ledger \
+    --rpc-port 8899 \
+    --private-rpc \
+    --dynamic-port-range 8000-8010 \
+    --entrypoint entrypoint.mainnet-beta.solana.com:8001 \
+    --entrypoint entrypoint2.mainnet-beta.solana.com:8001 \
+    --entrypoint entrypoint3.mainnet-beta.solana.com:8001 \
+    --entrypoint entrypoint4.mainnet-beta.solana.com:8001 \
+    --entrypoint entrypoint5.mainnet-beta.solana.com:8001 \
+    --expected-genesis-hash 5eykt4UsFv8P8NJdTREpY1vzqKqZKvdpKuc147dw2N9d \
+    --wal-recovery-mode skip_any_corrupted_record \
+    --limit-ledger-size
+```
+
+All four [`--known-validator`s](running-validator/validator-start.md#known-validators)
+are operated by Solana Labs

package/src/css/custom.css

@@ -0,0 +1,73 @@
+/* stylelint-disable docusaurus/copyright-header */
+/**
+ * Any CSS included here will be global. The classic template
+ * bundles Infima by default. Infima is a CSS framework designed to
+ * work well for content-centric websites.
+ */
+
+/* You can override the default Infima variables here. */
+
+@import url('https://fonts.googleapis.com/css2?family=Roboto');
+
+:root {
+  --ifm-color-primary: #25c2a0;
+  --ifm-color-primary-dark: #409088;
+  --ifm-color-primary-darker: #387462;
+  --ifm-color-primary-darkest: #1b4e3f;
+  --ifm-color-primary-light: #42ba96;
+  --ifm-color-primary-lighter: #86b8b6;
+  --ifm-color-primary-lightest: #abd5c6;
+  --ifm-code-font-size: 95%;
+  --ifm-spacing-horizontal: 1em;
+  --ifm-font-family-base: "Roboto", system-ui, -apple-system, Segoe UI, Roboto, Ubuntu, Cantarell, Noto Sans, sans-serif, BlinkMacSystemFont, 'Segoe UI', Helvetica, Arial, sans-serif, 'Apple Color Emoji', 'Segoe UI Emoji', 'Segoe UI Symbol';
+  --ifm-footer-background-color: #232323;
+}
+
+
+
+
+@keyframes fadeInUp {
+  0% { opacity: 0; transform: translateY(1.5rem); }
+}
+
+main {
+  margin: 1rem 0 5rem 0;
+}
+
+.docusaurus-highlight-code-line {
+  background-color: rgb(72, 77, 91);
+  display: block;
+  margin: 0 calc(-1 * var(--ifm-pre-padding));
+  padding: 0 var(--ifm-pre-padding);
+}
+
+.card {
+  padding: 1rem;
+  margin-top: 0rem;
+  animation: fadeInUp 400ms backwards;
+  animation-delay: 150ms;
+  transition-property: all;
+  transition-duration: 200ms;
+  box-shadow: 0 8px 28px 4px rgba(86,91,115,0.15);
+}
+
+
+.card a {
+  text-decoration: none;
+}
+
+.card:hover {
+  transform: translate(0px, -5px);
+}
+
+.footer--dark {
+  background-color: #232323 !important;
+}
+
+footer .text--center {
+  padding: 2rem 0 0 0;
+}
+
+.card__header h3 {
+  color: #1DD79B;
+}

package/src/developing/backwards-compatibility.md

@@ -0,0 +1,151 @@
+---
+title: Backward Compatibility Policy
+---
+
+As the Solana developer ecosystem grows, so does the need for clear expectations around
+breaking API and behavior changes affecting applications and tooling built for Solana.
+In a perfect world, Solana development could continue at a very fast pace without ever
+causing issues for existing developers. However, some compromises will need to be made
+and so this document attempts to clarify and codify the process for new releases.
+
+### Expectations
+
+- Solana software releases include APIs, SDKs, and CLI tooling (with a few [exceptions](#exceptions)).
+- Solana software releases follow semantic versioning, more details below.
+- Software for a `MINOR` version release will be compatible across all software on the
+  same `MAJOR` version.
+
+### Deprecation Process
+
+1. In any `PATCH` or `MINOR` release, a feature, API, endpoint, etc. could be marked as deprecated.
+2. According to code upgrade difficulty, some features will be remain deprecated for a few release
+   cycles.
+3. In a future `MAJOR` release, deprecated features will be removed in an incompatible way.
+
+### Release Cadence
+
+The Solana RPC API, Rust SDK, CLI tooling, and BPF Program SDK are all updated and shipped
+along with each Solana software release and should always be compatible between `PATCH`
+updates of a particular `MINOR` version release.
+
+#### Release Channels
+
+- `edge` software that contains cutting-edge features with no backward compatibility policy
+- `beta` software that runs on the Solana Testnet cluster
+- `stable` software that run on the Solana Mainnet Beta and Devnet clusters
+
+#### Major Releases (x.0.0)
+
+`MAJOR` version releases (e.g. 2.0.0) may contain breaking changes and removal of previously
+deprecated features. Client SDKs and tooling will begin using new features and endpoints
+that were enabled in the previous `MAJOR` version.
+
+#### Minor Releases (1.x.0)
+
+New features and proposal implementations are added to _new_ `MINOR` version
+releases (e.g. 1.4.0) and are first run on Solana's Testnet cluster. While running
+on the testnet, `MINOR` versions are considered to be in the `beta` release channel. After
+those changes have been patched as needed and proven to be reliable, the `MINOR` version will
+be upgraded to the `stable` release channel and deployed to the Mainnet Beta cluster.
+
+#### Patch Releases (1.0.x)
+
+Low risk features, non-breaking changes, and security and bug fixes are shipped as part
+of `PATCH` version releases (e.g. 1.0.11). Patches may be applied to both `beta` and `stable`
+release channels.
+
+### RPC API
+
+Patch releases:
+
+- Bug fixes
+- Security fixes
+- Endpoint / feature deprecation
+
+Minor releases:
+
+- New RPC endpoints and features
+
+Major releases:
+
+- Removal of deprecated features
+
+### Rust Crates
+
+- [`solana-sdk`](https://docs.rs/solana-sdk/) - Rust SDK for creating transactions and parsing account state
+- [`solana-program`](https://docs.rs/solana-program/) - Rust SDK for writing programs
+- [`solana-client`](https://docs.rs/solana-client/) - Rust client for connecting to RPC API
+- [`solana-cli-config`](https://docs.rs/solana-cli-config/) - Rust client for managing Solana CLI config files
+- [`solana-accountsdb-plugin-interface`](https://docs.rs/solana-accountsdb-plugin-interface/) - Rust interface for developing Solana AccountsDb plugins.
+
+Patch releases:
+
+- Bug fixes
+- Security fixes
+- Performance improvements
+
+Minor releases:
+
+- New APIs
+
+Major releases
+
+- Removal of deprecated APIs
+- Backwards incompatible behavior changes
+
+### CLI Tools
+
+Patch releases:
+
+- Bug and security fixes
+- Performance improvements
+- Subcommand / argument deprecation
+
+Minor releases:
+
+- New subcommands
+
+Major releases:
+
+- Switch to new RPC API endpoints / configuration introduced in the previous major version.
+- Removal of deprecated features
+
+### Runtime Features
+
+New Solana runtime features are feature-switched and manually activated. Runtime features
+include: the introduction of new native programs, sysvars, and syscalls; and changes to
+their behavior. Feature activation is cluster agnostic, allowing confidence to be built on
+Testnet before activation on Mainnet-beta.
+
+The release process is as follows:
+
+1. New runtime feature is included in a new release, deactivated by default
+2. Once sufficient staked validators upgrade to the new release, the runtime feature switch
+   is activated manually with an instruction
+3. The feature takes effect at the beginning of the next epoch
+
+### Infrastructure Changes
+
+#### Public API Nodes
+
+Solana provides publicly available RPC API nodes for all developers to use. The Solana team
+will make their best effort to communicate any changes to the host, port, rate-limiting behavior,
+availability, etc. However, we recommend that developers rely on their own validator nodes to
+discourage dependence upon Solana operated nodes.
+
+#### Local cluster scripts and Docker images
+
+Breaking changes will be limited to `MAJOR` version updates. `MINOR` and `PATCH` updates should always
+be backwards compatible.
+
+### Exceptions
+
+#### Web3 JavaScript SDK
+
+The Web3.JS SDK also follows semantic versioning specifications but is shipped separately from Solana
+software releases.
+
+#### Attack Vectors
+
+If a new attack vector is discovered in existing code, the above processes may be
+circumvented in order to rapidly deploy a fix, depending on the severity of the issue.