From 57add5366e40abaffd3b29a13357fbf34af59dd3 Mon Sep 17 00:00:00 2001
From: "mergify[bot]" <37929162+mergify[bot]@users.noreply.github.com>
Date: Tue, 20 Apr 2021 09:33:40 +0000
Subject: [PATCH] Expand a couple docs sections (backport #16664) (#16671)

* docs: Flesh out address verification in integraion guide

(cherry picked from commit d575450ef0ccb11908d2b0369e99fc1f0bc844be)

* docs: Expand native program descriptions

(cherry picked from commit 12678a819d758dc8b00aa8ec7c98dce6204c060b)

Co-authored-by: Trent Nelson <trent@solana.com>
---
 .../developing/runtime-facilities/programs.md | 10 +++++----
 docs/src/integrations/exchange.md             | 21 +++++++++++++++++++
 2 files changed, 27 insertions(+), 4 deletions(-)

diff --git a/docs/src/developing/runtime-facilities/programs.md b/docs/src/developing/runtime-facilities/programs.md
index ef9cd8e13a..d5ebc8ec19 100644
--- a/docs/src/developing/runtime-facilities/programs.md
+++ b/docs/src/developing/runtime-facilities/programs.md
@@ -17,7 +17,8 @@ programs, as well include instructions from on-chain programs.
 
 ## System Program
 
-Create accounts and transfer lamports between them
+Create new accounts, allocate account data, assign accounts to owning programs,
+transfer lamports from System Program owned accounts and pay transacation fees.
 
 - Program id: `11111111111111111111111111111111`
 - Instructions: [SystemInstruction](https://docs.rs/solana-sdk/VERSION_FOR_DOCS_RS/solana_sdk/system_instruction/enum.SystemInstruction.html)
@@ -36,21 +37,22 @@ data to store in it.
 
 ## Stake Program
 
-Create stake accounts and delegate it to validators
+Create and manage accounts representing stake and rewards for delegations to
+validators.
 
 - Program id: `Stake11111111111111111111111111111111111111`
 - Instructions: [StakeInstruction](https://docs.rs/solana-stake-program/VERSION_FOR_DOCS_RS/solana_stake_program/stake_instruction/enum.StakeInstruction.html)
 
 ## Vote Program
 
-Create vote accounts and vote on blocks
+Create and manage accounts that track validator voting state and rewards.
 
 - Program id: `Vote111111111111111111111111111111111111111`
 - Instructions: [VoteInstruction](https://docs.rs/solana-vote-program/VERSION_FOR_DOCS_RS/solana_vote_program/vote_instruction/enum.VoteInstruction.html)
 
 ## BPF Loader
 
-Add programs to the chain and execute them.
+Deploy programs to the chain, load and execute them.
 
 - Program id: `BPFLoader1111111111111111111111111111111111`
 - Instructions: [LoaderInstruction](https://docs.rs/solana-sdk/VERSION_FOR_DOCS_RS/solana_sdk/loader_instruction/enum.LoaderInstruction.html)
diff --git a/docs/src/integrations/exchange.md b/docs/src/integrations/exchange.md
index bdd7cf50c1..cf478bbbe2 100644
--- a/docs/src/integrations/exchange.md
+++ b/docs/src/integrations/exchange.md
@@ -480,6 +480,27 @@ As withdrawals are irreversible, it may be a good practice to validate a
 user-supplied account address before authorizing a withdrawal in order to
 prevent accidental loss of user funds.
 
+#### Basic verfication
+
+Solana addresses a 32-byte array, encoded with the bitcoin base58 alphabet. This
+results in an ASCII text string matching the following regular expression:
+```
+[1-9A-HJ-NP-Za-km-z]{32,44}
+```
+This check is insufficient on its own as Solana addresses are not checksummed, so
+typos cannot be detected. To further validate the user's input, the string can be
+decoded and the resulting byte array's length confirmed to be 32. However, there
+are some addresses that can decode to 32 bytes despite a typo such as a single
+missing character, reversed characters and ignored case
+
+#### Advanced verification
+
+Due to the vulnerability to typos described above, it is recommended that the
+balance be queried for candidate withdraw addresses and the user prompted to
+confirm their intentions if a non-zero balance is discovered.
+
+#### Valid ed25519 pubkey check
+
 The address of a normal account in Solana is a Base58-encoded string of a
 256-bit ed25519 public key. Not all bit patterns are valid public keys for the
 ed25519 curve, so it is possible to ensure user-supplied account addresses are