Rework docs for Pubkey::find_program_address and friends

[brson]

Problem

This is a crucial function to understand, but learning how to use it correctly took me a long time.

Summary of Changes

• Make find_program_address the first listed of {find,try_find,create}_program_address, as it is the function most callers should use.
• Add a comprehensive example to find_program_address
• Rework find_program_address's docs to synthesize its prior docs, create_program_address's, and my own learnings
• Strongly indicate that create_program_address should not be used.

This adds anyhow and solana-sdk as dev-dependencies to solana-program. The solana-sdk is a weird semi-circular dependency but it works because compiling for tests results in a technically different crate than normal compilation.

Please read these carefully for accuracy, particularly this passage:

As all account addresses accessed by an on-chain Solana program must be explicitly passed to the program, it is typical for the PDAs to be derived in off-chain client programs, avoiding the compute cost of generating the address on-chain. The address may or may not then be verified by re-deriving it on-chain, depending on the requirements of the program.

As well as any instances of language like "commonly", "typically", "conventionally", etc.

[brson]

CI doesn't like the circular dependency. I'll remove it.

[brson]

Circular dependency removed at the expense of ignoring an example.

[brson]

CI failure looks unrelated

[CriesofCarrots]

This looks great to me, and your verbiage seems correct. I'll ask @jackcmay to take a pass also.

A few nits, most of which are on text predating your changes, if you would be so kind? (I know commas are the nittiest of nits, but I only included spots I actually got hung up)

[jackcmay]

lgtm after @CriesofCarrots suggestions, thanks!

[codecov]

Codecov Report

Merging #21528 (ec3aba7) into master (393c765) will increase coverage by 0.1%.
The diff coverage is 100.0%.

@@            Coverage Diff            @@
##           master   #21528     +/-   ##
=========================================
+ Coverage    81.4%    81.6%   +0.1%     
=========================================
  Files         540      505     -35     
  Lines      143840   141768   -2072     
  Branches      296        0    -296     
=========================================
- Hits       117162   115685   -1477     
+ Misses      26577    26083    -494     
+ Partials      101        0    -101     

Pull request has been modified.

[brson]

@CriesofCarrots applied your suggestions, alphabetized the dev-dependencies, and fixed a bogus commit message.

[brson]

CI failure looks unrelated.

[CriesofCarrots]

lgtm!

[askibin]

why it says this for create_program_address:
"it may unpredictably return an error and should not be used. It exists for backwards compatibility reasons" ?
this is not the case, create_program_address is used extensively to verify a PDA with given seeds and bump

[brson]

why it says this for create_program_address: "it may unpredictably return an error and should not be used. It exists for backwards compatibility reasons" ? this is not the case, create_program_address is used extensively to verify a PDA with given seeds and bump

I was not aware of this use of create_program_address. Thanks for informing me. I'll produce a follow up patch.