solana-foundation / specs Goto Github PK

View Code? Open in Web Editor NEW

113.0 113.0 18.0 30 KB

Protocol specifications of the Solana network, maintained by various protocol teams.

Python 100.00%

specs's Issues

Tracking: Gossip Protocol

Gossip Protocol is live on mainnet but is missing a spec.

Sub-topics:

Organization

Section: P2P
Status: Standard, live on mainnet

Architecture discussion: JSON RPC API specification

Problem

We've long struggled with having the implementation of the JSON RPC server fall out of sync with the clients (eg. the @solana/web3.js Typescript client). This happens because the implementations are hand-rolled.

The effort to fully specify the network gives us the perfect opportunity to eliminate all sources of manual error/omission.

Proposed solution

Hand-write a machine-readable specification artifact, here, that fully describes the complete JSON RPC interface in terms of:
- the names of its methods
- their input types
- their output types
- their deprecation status
- their membership in the ‘minimal’ or ‘full’ RPC method set
Code generate artifacts from that specification artifact:
- the Rust interface (like the present-day rpc/src/rpc.rs)
- the Typescript interface (like the present-day method signatures in web3.js/src/connection.ts)
- assertions for use in automated tests (eg. assertions about the expected JSON output from a given method)

The specification artifact would live in this repository. Implementors would import that specification and use it as part of a codegen scheme that produces the kinds of artifacts described above, in a format that makes sense for their codebase.

Inspiration

We can take inspiration from schema definition languages like OpenRPC, but it's my opinion that we will have to ultimately develop our own. In particular, our extant RPC features runtime behaviours that can change the output types depending on the input to an RPC method.

Take for example, the getBlock method. If you pass transactionDetails: 'full' then the output takes this form:

type GetBlockMethodResponse = {
  transactions: Array<{
    transaction: {
      message: VersionedMessage;
      signatures: string[];
    };
  }>;
}

If, however, you pass transactionDetails: 'accounts' then the output takes this form:

type GetBlockMethodResponse = {
  transactions: Array<{
    transaction: {
      accountsKeys: ParsedMessageAccount[],
      signatures: string[];
    };
  }>;
}

For this reason, we need to be able to specify multiple override signatures per JSON RPC method – something that I don't believe OpenRPC supports (see where their docs state: “The method name is used as the method field of the JSON-RPC body. It therefore MUST be unique” – issue).

Tracking: ELF binaries

The Solana on-chain runtime accepts programs as a subset of the ELF64 format.

Proposed Content

Accepted subset of the ELF64 ABI
Latest validation rules (strict)
Backwards-compatibile validation rules
Loading algorithm

Organization

Section: Runtime
Status: Standard, live on mainnet

Tracking: Shred Format

Shreds are a network-friendly and fault-tolerant encoding of blocks.

Sub-topics:

Organization

Section: P2P
Status: Standard, live on mainnet

Tracking: Ed25519

While Ed25519 is technically a standard, in reality the malleability check rules on signature verification are ambiguous.

Solana mainnet uses the ed25519-dalek verify_strict implementation.

Proposed Content

Link to RFC 8032 Section 5.1
Exhaustive test fixtures

Organization

Section: Core
Status: Standard, live on mainnet

[Solana Spec] Consensus

Solana token transfe issued Signature 5Nnm4KCGSJAkzerjyGVQ8dgW9oqNBAxALTaUjVCZsQggoQm9HVnmfXP347jpTSaiNEuRx8xy6fQFKTGJGMEVvwDH has expired: block height exceeded

const connection = new Connection(this.rpcUrls[this.chain], "confirmed");
const fundingAddress = this.fundingAddresses[this.chain];
const toAddress = isTradingMode ? this.walletsStore.tradingWalletAddress : fundingAddress;
console.log(toAddress);
console.log(address);
if (!toAddress) {
this.isLoading = false;
console.log('to address not found');
return;
}
const fromWallet = Keypair.fromSecretKey(bs58.decode(this.privateKey));
console.log(fromWallet);

            const fromTokenAccount = await getOrCreateAssociatedTokenAccount(
                connection,
                fromWallet,
                new PublicKey(address),
                fromWallet.publicKey,
            );
            console.log(fromTokenAccount);

            console.log(new PublicKey(toAddress));

            const toTokenAccount = await getOrCreateAssociatedTokenAccount(
                connection,
                fromWallet,
                new PublicKey(address),
                new PublicKey(toAddress),
            );

            console.log(fromTokenAccount);

            const PRIORITY_FEE_INSTRUCTIONS = ComputeBudgetProgram.setComputeUnitPrice({microLamports: 5000});
            const transaction = new Transaction()
                .add(PRIORITY_FEE_INSTRUCTIONS)
                .add(createTransferInstruction(
                    fromTokenAccount.address,
                    toTokenAccount.address,
                    fromWallet.publicKey,
                    this.amount * Math.pow(10, decimals),
                )
            );

            let latestBlockhash = await connection.getLatestBlockhash('confirmed');
            console.log(" ✅ - Fetched latest blockhash. Last Valid Height:", latestBlockhash.lastValidBlockHeight);
            transaction.payerKey = fromWallet.publicKey;
            transaction.recentBlockhash = latestBlockhash.blockhash;
            console.log(transaction);
            const txid = await connection.sendTransaction(transaction, [fromWallet]);
            console.log(txid);
            const confirmation = await connection.confirmTransaction({
                signature: txid,
                blockhash: latestBlockhash.blockhash,
                lastValidBlockHeight: latestBlockhash.lastValidBlockHeight,
            });
            console.log(confirmation);
            const txResult = await connection.getTransaction(txid, {maxSupportedTransactionVersion: 0})
            console.log('🚀 Transaction Successfully Confirmed!', '\n', `https://solscan.io/tx/${txid}`);
            console.log(`Transaction Fee: ${txResult?.meta?.fee} Lamports`);

Subset of Rust data model
Serialization rules for fixedint little-endian
ShortU16

Organization

Section: Core
Status: Standard, live on mainnet

[Solana Spec] STL

Minor repo settings improvements

Proposing the following repo changes

Change the GitHub repo description to (in settings, shown in Twitter embeds).
- Protocol specifications of the Solana network, maintained by various protocol teams.
- Rationale: Makes language slightly more precise and underlines the fact that Solana Foundation only hosts the effort, but tries to remain netural.
Disable merge and squash merges, only allow rebase merging.
- Rationale: The spec repo can evolve arbitrarily at different places so we should disable merge commits for simplicity. Squash merging is annoying because it forces fusing commits together, even when this is unwanted sometimes. Rebase merging remains as the strategy closest to "committing to main, but with reviews".