Expand solana-sdk API docs. (#29063)
* Expand solana-sdk API docs. * Update sdk/src/genesis_config.rs Co-authored-by: Tyera <teulberg@gmail.com> * Update sdk/src/hard_forks.rs Co-authored-by: Tyera <teulberg@gmail.com> * Update sdk/src/builtins.rs Co-authored-by: Tyera <teulberg@gmail.com> * Update sdk/src/builtins.rs Co-authored-by: Tyera <teulberg@gmail.com> * Update sdk/src/rpc_port.rs Co-authored-by: Tyera <teulberg@gmail.com> * Update sdk/src/lib.rs Co-authored-by: Tyera <teulberg@gmail.com> * Clarify derivation_path docs * 'entry point' -> 'entrypoint' Co-authored-by: Tyera <teulberg@gmail.com>
This commit is contained in:
parent
bf18613a2e
commit
edd5f6f3be
|
@ -1,4 +1,4 @@
|
|||
//! The Rust-based BPF program entry point supported by the latest BPF loader.
|
||||
//! The Rust-based BPF program entrypoint supported by the latest BPF loader.
|
||||
//!
|
||||
//! For more information see the [`bpf_loader`] module.
|
||||
//!
|
||||
|
@ -39,7 +39,7 @@ pub const HEAP_LENGTH: usize = 32 * 1024;
|
|||
/// Value used to indicate that a serialized account is not a duplicate
|
||||
pub const NON_DUP_MARKER: u8 = u8::MAX;
|
||||
|
||||
/// Declare the program entry point and set up global handlers.
|
||||
/// Declare the program entrypoint and set up global handlers.
|
||||
///
|
||||
/// This macro emits the common boilerplate necessary to begin program
|
||||
/// execution, calling a provided function to process the program instruction
|
||||
|
@ -91,7 +91,7 @@ pub const NON_DUP_MARKER: u8 = u8::MAX;
|
|||
///
|
||||
/// # Examples
|
||||
///
|
||||
/// Defining an entry point and making it conditional on the `no-entrypoint`
|
||||
/// Defining an entrypoint and making it conditional on the `no-entrypoint`
|
||||
/// feature. Although the `entrypoint` module is written inline in this example,
|
||||
/// it is common to put it into its own file.
|
||||
///
|
||||
|
|
|
@ -1,4 +1,4 @@
|
|||
//! The Rust-based BPF program entry point supported by the original BPF loader.
|
||||
//! The Rust-based BPF program entrypoint supported by the original BPF loader.
|
||||
//!
|
||||
//! The original BPF loader is deprecated and exists for backwards-compatibility
|
||||
//! reasons. This module should not be used by new programs.
|
||||
|
@ -35,11 +35,11 @@ pub type ProcessInstruction =
|
|||
/// Programs indicate success with a return value of 0
|
||||
pub const SUCCESS: u64 = 0;
|
||||
|
||||
/// Declare the program entry point.
|
||||
/// Declare the program entrypoint.
|
||||
///
|
||||
/// Deserialize the program input arguments and call
|
||||
/// the user defined `process_instruction` function.
|
||||
/// Users must call this macro otherwise an entry point for
|
||||
/// Users must call this macro otherwise an entrypoint for
|
||||
/// their program will not be created.
|
||||
#[macro_export]
|
||||
macro_rules! entrypoint_deprecated {
|
||||
|
|
|
@ -546,7 +546,7 @@ pub mod config {
|
|||
}
|
||||
}
|
||||
|
||||
/// A vector of Solana SDK IDs
|
||||
/// A vector of Solana SDK IDs.
|
||||
pub mod sdk_ids {
|
||||
use {
|
||||
crate::{
|
||||
|
|
|
@ -1,3 +1,5 @@
|
|||
//! The Solana [`Account`] type.
|
||||
|
||||
use {
|
||||
crate::{
|
||||
clock::{Epoch, INITIAL_RENT_EPOCH},
|
||||
|
|
|
@ -1,4 +1,5 @@
|
|||
//! useful extras for Account state
|
||||
//! Useful extras for `Account` state.
|
||||
|
||||
use {
|
||||
crate::{
|
||||
account::{Account, AccountSharedData},
|
||||
|
|
|
@ -1,4 +1,4 @@
|
|||
//! Solana builtin helper macros
|
||||
//! Solana helper macros for declaring built-in programs.
|
||||
|
||||
#[rustversion::since(1.46.0)]
|
||||
#[macro_export]
|
||||
|
@ -58,7 +58,7 @@ macro_rules! declare_builtin_name {
|
|||
};
|
||||
}
|
||||
|
||||
/// Convenience macro to declare a builtin
|
||||
/// Convenience macro to declare a built-in program.
|
||||
///
|
||||
/// bs58_string: bs58 string representation the program's id
|
||||
/// name: Name of the program
|
||||
|
|
|
@ -1,3 +1,5 @@
|
|||
//! Definitions of commitment levels.
|
||||
|
||||
#![allow(deprecated)]
|
||||
#![cfg(feature = "full")]
|
||||
|
||||
|
|
|
@ -1,3 +1,5 @@
|
|||
//! The compute budget native program.
|
||||
|
||||
#![cfg(feature = "full")]
|
||||
|
||||
use {
|
||||
|
|
|
@ -1,3 +1,14 @@
|
|||
//! [BIP-44] derivation paths.
|
||||
//!
|
||||
//! [BIP-44]: https://github.com/bitcoin/bips/blob/master/bip-0044.mediawiki
|
||||
//!
|
||||
//! Includes definitions and helpers for Solana derivation paths.
|
||||
//! The standard Solana BIP-44 derivation path prefix is
|
||||
//!
|
||||
//! > `m/44'/501'`
|
||||
//!
|
||||
//! with 501 being the Solana coin type.
|
||||
|
||||
use {
|
||||
core::{iter::IntoIterator, slice::Iter},
|
||||
derivation_path::{ChildIndex, DerivationPath as DerivationPathInner},
|
||||
|
|
|
@ -1,3 +1,5 @@
|
|||
//! Serde helpers.
|
||||
|
||||
use serde::{Deserialize, Deserializer};
|
||||
|
||||
/// This helper function enables successful deserialization of versioned structs; new structs may
|
||||
|
|
|
@ -1,3 +1,7 @@
|
|||
//! Instructions for the [ed25519 native program][np].
|
||||
//!
|
||||
//! [np]: https://docs.solana.com/developing/runtime-facilities/programs#ed25519-program
|
||||
|
||||
#![cfg(feature = "full")]
|
||||
|
||||
use {
|
||||
|
|
|
@ -1,3 +1,9 @@
|
|||
//! The Rust-based BPF program entrypoint supported by the latest BPF loader.
|
||||
//!
|
||||
//! For more information see the [`bpf_loader`] module.
|
||||
//!
|
||||
//! [`bpf_loader`]: crate::bpf_loader
|
||||
|
||||
pub use solana_program::entrypoint::*;
|
||||
|
||||
#[macro_export]
|
||||
|
|
|
@ -1,3 +1,12 @@
|
|||
//! The Rust-based BPF program entrypoint supported by the original BPF loader.
|
||||
//!
|
||||
//! The original BPF loader is deprecated and exists for backwards-compatibility
|
||||
//! reasons. This module should not be used by new programs.
|
||||
//!
|
||||
//! For more information see the [`bpf_loader_deprecated`] module.
|
||||
//!
|
||||
//! [`bpf_loader_deprecated`]: crate::bpf_loader_deprecated
|
||||
|
||||
pub use solana_program::entrypoint_deprecated::*;
|
||||
|
||||
#[macro_export]
|
||||
|
|
|
@ -1,3 +1,9 @@
|
|||
//! Information about the current epoch.
|
||||
//!
|
||||
//! As returned by the [`getEpochInfo`] RPC method.
|
||||
//!
|
||||
//! [`getEpochInfo`]: https://docs.solana.com/developing/clients/jsonrpc-api#getepochinfo
|
||||
|
||||
use crate::clock::{Epoch, Slot};
|
||||
|
||||
#[derive(Serialize, Deserialize, Clone, Debug, Eq, PartialEq)]
|
||||
|
|
|
@ -1,3 +1,5 @@
|
|||
//! Used by validators to run events on exit.
|
||||
|
||||
use std::fmt;
|
||||
|
||||
#[derive(Default)]
|
||||
|
|
|
@ -1,3 +1,5 @@
|
|||
//! Fee structures.
|
||||
|
||||
use crate::native_token::sol_to_lamports;
|
||||
|
||||
/// A fee and its associated compute unit limit
|
||||
|
|
|
@ -1,4 +1,4 @@
|
|||
//! The `genesis_config` module is a library for generating the chain's genesis config.
|
||||
//! The chain's genesis config.
|
||||
|
||||
#![cfg(feature = "full")]
|
||||
|
||||
|
|
|
@ -1,5 +1,5 @@
|
|||
//! The `hard_forks` module is used to maintain the list of slot boundaries for when a hard fork
|
||||
//! should occur.
|
||||
//! The list of slot boundaries at which a hard fork should
|
||||
//! occur.
|
||||
|
||||
#![cfg(feature = "full")]
|
||||
|
||||
|
|
|
@ -1,6 +1,11 @@
|
|||
//! Hashing with the [SHA-256] hash function, and a general [`Hash`] type.
|
||||
//!
|
||||
//! [SHA-256]: https://en.wikipedia.org/wiki/SHA-2
|
||||
//! [`Hash`]: struct@Hash
|
||||
|
||||
pub use solana_program::hash::*;
|
||||
|
||||
/// random hash value for tests and benchmarks.
|
||||
/// Random hash value for tests and benchmarks.
|
||||
#[cfg(feature = "full")]
|
||||
pub fn new_rand<R: ?Sized>(rng: &mut R) -> Hash
|
||||
where
|
||||
|
|
|
@ -1,3 +1,34 @@
|
|||
//! The Solana host and client SDK.
|
||||
//!
|
||||
//! This is the base library for all off-chain programs that interact with
|
||||
//! Solana or otherwise operate on Solana data structures. On-chain programs
|
||||
//! instead use the [`solana-program`] crate, the modules of which are
|
||||
//! re-exported by this crate, like the relationship between the Rust
|
||||
//! `core` and `std` crates. As much of the functionality of this crate is
|
||||
//! provided by `solana-program`, see that crate's documentation for an
|
||||
//! overview.
|
||||
//!
|
||||
//! [`solana-program`]: https://docs.rs/solana-program
|
||||
//!
|
||||
//! Many of the modules in this crate are primarily of use to the Solana runtime
|
||||
//! itself. Additional crates provide capabilities built on `solana-sdk`, and
|
||||
//! many programs will need to link to those crates as well, particularly for
|
||||
//! clients communicating with Solana nodes over RPC.
|
||||
//!
|
||||
//! Such crates include:
|
||||
//!
|
||||
//! - [`solana-client`] - For interacting with a Solana node via the [JSON-RPC API][json].
|
||||
//! - [`solana-cli-config`] - Loading and saving the Solana CLI configuration file.
|
||||
//! - [`solana-clap-utils`] - Routines for setting up the CLI using [`clap`], as
|
||||
//! used by the Solana CLI. Includes functions for loading all types of
|
||||
//! signers supported by the CLI.
|
||||
//!
|
||||
//! [`solana-client`]: https://docs.rs/solana-client
|
||||
//! [`solana-cli-config`]: https://docs.rs/solana-cli-config
|
||||
//! [`solana-clap-utils`]: https://docs.rs/solana-clap-utils
|
||||
//! [json]: https://docs.solana.com/developing/clients/jsonrpc-api
|
||||
//! [`clap`]: https://docs.rs/clap
|
||||
|
||||
#![allow(incomplete_features)]
|
||||
#![cfg_attr(RUSTC_WITH_SPECIALIZATION, feature(specialization))]
|
||||
#![cfg_attr(RUSTC_NEEDS_PROC_MACRO_HYGIENE, feature(proc_macro_hygiene))]
|
||||
|
@ -68,9 +99,9 @@ pub mod transaction_context;
|
|||
pub mod transport;
|
||||
pub mod wasm;
|
||||
|
||||
/// Same as `declare_id` except report that this id has been deprecated
|
||||
/// Same as `declare_id` except report that this id has been deprecated.
|
||||
pub use solana_sdk_macro::declare_deprecated_id;
|
||||
/// Convenience macro to declare a static public key and functions to interact with it
|
||||
/// Convenience macro to declare a static public key and functions to interact with it.
|
||||
///
|
||||
/// Input: a single literal base58 string representation of a program's id
|
||||
///
|
||||
|
@ -92,7 +123,7 @@ pub use solana_sdk_macro::declare_deprecated_id;
|
|||
/// assert_eq!(id(), my_id);
|
||||
/// ```
|
||||
pub use solana_sdk_macro::declare_id;
|
||||
/// Convenience macro to define a static public key
|
||||
/// Convenience macro to define a static public key.
|
||||
///
|
||||
/// Input: a single literal base58 string representation of a Pubkey
|
||||
///
|
||||
|
@ -108,6 +139,7 @@ pub use solana_sdk_macro::declare_id;
|
|||
/// assert_eq!(ID, my_id);
|
||||
/// ```
|
||||
pub use solana_sdk_macro::pubkey;
|
||||
/// Convenience macro to define multiple static public keys.
|
||||
pub use solana_sdk_macro::pubkeys;
|
||||
#[rustversion::since(1.46.0)]
|
||||
pub use solana_sdk_macro::respan;
|
||||
|
|
|
@ -1,3 +1,5 @@
|
|||
//! The native loader native program.
|
||||
|
||||
use crate::{
|
||||
account::{
|
||||
Account, AccountSharedData, InheritableAccountFields, DUMMY_INHERITABLE_ACCOUNT_FIELDS,
|
||||
|
|
|
@ -1,3 +1,5 @@
|
|||
//! Functions related to nonce accounts.
|
||||
|
||||
use {
|
||||
crate::{
|
||||
account::{AccountSharedData, ReadableAccount},
|
||||
|
|
|
@ -1,4 +1,4 @@
|
|||
//! Off-Chain Message container for storing non-transaction messages.
|
||||
//! Off-chain message container for storing non-transaction messages.
|
||||
|
||||
#![cfg(feature = "full")]
|
||||
|
||||
|
|
|
@ -1,3 +1,5 @@
|
|||
//! The definition of a Solana network packet.
|
||||
|
||||
use {
|
||||
bincode::{Options, Result},
|
||||
bitflags::bitflags,
|
||||
|
|
|
@ -1,3 +1,5 @@
|
|||
//! Definitions of Solana's proof of history.
|
||||
|
||||
use {
|
||||
crate::{clock::DEFAULT_TICKS_PER_SECOND, unchecked_div_by_const},
|
||||
std::time::Duration,
|
||||
|
|
|
@ -1,4 +1,4 @@
|
|||
//! Solana precompiled programs
|
||||
//! Solana precompiled programs.
|
||||
|
||||
#![cfg(feature = "full")]
|
||||
|
||||
|
|
|
@ -1,3 +1,7 @@
|
|||
//! Contains a single utility function for deserializing from [bincode].
|
||||
//!
|
||||
//! [bincode]: https://docs.rs/bincode
|
||||
|
||||
use crate::instruction::InstructionError;
|
||||
|
||||
/// Deserialize with a limit based the maximum amount of data a program can expect to get.
|
||||
|
|
|
@ -1,3 +1,5 @@
|
|||
//! Solana account addresses.
|
||||
|
||||
pub use solana_program::pubkey::*;
|
||||
|
||||
/// New random Pubkey for tests and benchmarks.
|
||||
|
|
|
@ -1,3 +1,5 @@
|
|||
//! Definitions related to Solana over QUIC.
|
||||
|
||||
pub const QUIC_PORT_OFFSET: u16 = 6;
|
||||
// Empirically found max number of concurrent streams
|
||||
// that seems to maximize TPS on GCE (higher values don't seem to
|
||||
|
|
|
@ -1,3 +1,5 @@
|
|||
//! Helpers for the recent blockhashes sysvar.
|
||||
|
||||
#[allow(deprecated)]
|
||||
use solana_program::sysvar::recent_blockhashes::{
|
||||
IntoIterSorted, IterItem, RecentBlockhashes, MAX_ENTRIES,
|
||||
|
|
|
@ -1,3 +1,5 @@
|
|||
//! Enumeration of reward types.
|
||||
|
||||
use std::fmt;
|
||||
|
||||
#[derive(Debug, PartialEq, Eq, Serialize, Deserialize, AbiExample, AbiEnumVisitor, Clone, Copy)]
|
||||
|
|
|
@ -1,3 +1,5 @@
|
|||
//! RPC default port numbers.
|
||||
|
||||
/// Default port number for JSON RPC API
|
||||
pub const DEFAULT_RPC_PORT: u16 = 8899;
|
||||
pub const DEFAULT_RPC_PORT_STR: &str = "8899";
|
||||
|
|
|
@ -1,3 +1,7 @@
|
|||
//! Calculation of [shred] versions.
|
||||
//!
|
||||
//! [shred]: https://docs.solana.com/terminology#shred
|
||||
|
||||
#![cfg(feature = "full")]
|
||||
|
||||
use solana_sdk::{
|
||||
|
|
|
@ -1,4 +1,4 @@
|
|||
//! The `signature` module provides functionality for public, and private keys.
|
||||
//! Functionality for public and private keys.
|
||||
#![cfg(feature = "full")]
|
||||
|
||||
// legacy module paths
|
||||
|
|
|
@ -1,3 +1,5 @@
|
|||
//! Abstractions and implementations for transaction signers.
|
||||
|
||||
#![cfg(feature = "full")]
|
||||
|
||||
use {
|
||||
|
|
|
@ -1,4 +1,4 @@
|
|||
//! Data shared between program runtime and built-in programs as well as SBF programs
|
||||
//! Data shared between program runtime and built-in programs as well as SBF programs.
|
||||
#![deny(clippy::indexing_slicing)]
|
||||
|
||||
#[cfg(not(target_os = "solana"))]
|
||||
|
|
|
@ -1,3 +1,5 @@
|
|||
//! Defines the [`TransportError`] type.
|
||||
|
||||
#![cfg(feature = "full")]
|
||||
|
||||
use {crate::transaction::TransactionError, std::io, thiserror::Error};
|
||||
|
|
Loading…
Reference in New Issue