lang, ts: Update discriminator-related documentation (#3211)

lang/attribute/account/src/lib.rs

@@ -25,14 +25,16 @@ mod id;
 /// - [`Owner`](./trait.Owner.html)
 ///
 /// When implementing account serialization traits the first 8 bytes are
-/// reserved for a unique account discriminator, self described by the first 8
-/// bytes of the SHA256 of the account's Rust ident.
+/// reserved for a unique account discriminator by default, self described by
+/// the first 8 bytes of the SHA256 of the account's Rust ident. This is unless
+/// the discriminator was overridden with the `discriminator` argument (see
+/// [Arguments](#arguments)).
 ///
 /// As a result, any calls to `AccountDeserialize`'s `try_deserialize` will
 /// check this discriminator. If it doesn't match, an invalid account was given,
 /// and the account deserialization will exit with an error.
 ///
-/// # Args
+/// # Arguments
 ///
 /// - `discriminator`: Override the default 8-byte discriminator
 ///
@@ -83,8 +85,11 @@ mod id;
 /// [`safety`](https://docs.rs/bytemuck/latest/bytemuck/trait.Pod.html#safety)
 /// section before using.
 ///
-/// Using `zero_copy` requires adding the following to your `cargo.toml` file:
-/// `bytemuck = { version = "1.4.0", features = ["derive", "min_const_generics"]}`
+/// Using `zero_copy` requires adding the following dependency to your `Cargo.toml` file:
+///
+/// ```toml
+/// bytemuck = { version = "1.17", features = ["derive", "min_const_generics"] }
+/// ```
 #[proc_macro_attribute]
 pub fn account(
  args: proc_macro::TokenStream,

lang/attribute/event/src/lib.rs

@@ -11,7 +11,7 @@ use syn::parse_macro_input;
 /// their programs that clients can subscribe to. Currently, this macro is for
 /// structs only.
 ///
-/// # Args
+/// # Arguments
 ///
 /// - `discriminator`: Override the default 8-byte discriminator
 ///

lang/attribute/program/src/lib.rs

@@ -111,7 +111,7 @@ pub fn interface(
 
 /// This attribute is used to override the Anchor defaults of program instructions.
 ///
-/// # Args
+/// # Arguments
 ///
 /// - `discriminator`: Override the default 8-byte discriminator
 ///

lang/src/lib.rs

@@ -273,9 +273,8 @@ pub trait AccountDeserialize: Sized {
 pub trait ZeroCopy: Discriminator + Copy + Clone + Zeroable + Pod {}
 
 /// Calculates the data for an instruction invocation, where the data is
-/// `Sha256(<namespace>:<method_name>)[..8] || BorshSerialize(args)`.
-/// `args` is a borsh serialized struct of named fields for each argument given
-/// to an instruction.
+/// `Discriminator + BorshSerialize(args)`. `args` is a borsh serialized
+/// struct of named fields for each argument given to an instruction.
 pub trait InstructionData: Discriminator + AnchorSerialize {
  fn data(&self) -> Vec<u8> {
  let mut data = Vec::with_capacity(256);
@@ -300,8 +299,25 @@ pub trait Event: AnchorSerialize + AnchorDeserialize + Discriminator {
  fn data(&self) -> Vec<u8>;
 }
 
-/// 8 byte unique identifier for a type.
+/// Unique identifier for a type.
+///
+/// This is not a trait you should derive manually, as various Anchor macros already derive it
+/// internally.
+///
+/// Prior to Anchor v0.31, discriminators were always 8 bytes in size. However, starting with Anchor
+/// v0.31, it is possible to override the default discriminators, and discriminator length is no
+/// longer fixed, which means this trait can also be implemented for non-Anchor programs.
+///
+/// It's important that the discriminator is always unique for the type you're implementing it
+/// for. While the discriminator can be at any length (including zero), the IDL generation does not
+/// currently allow empty discriminators for safety and convenience reasons. However, the trait
+/// definition still allows empty discriminators because some non-Anchor programs, e.g. the SPL
+/// Token program, don't have account discriminators. In that case, safety checks should never
+/// depend on the discriminator.
 pub trait Discriminator {
+ /// Discriminator slice.
+ ///
+ /// See [`Discriminator`] trait documentation for more information.
  const DISCRIMINATOR: &'static [u8];
 }
 

lang/syn/src/codegen/program/dispatch.rs

@@ -61,19 +61,14 @@ pub fn generate(program: &Program) -> proc_macro2::TokenStream {
  quote! {
  /// Performs method dispatch.
  ///
- /// Each method in an anchor program is uniquely defined by a namespace
- /// and a rust identifier (i.e., the name given to the method). These
- /// two pieces can be combined to create a method identifier,
- /// specifically, Anchor uses
+ /// Each instruction's discriminator is checked until the given instruction data starts with
+ /// the current discriminator.
  ///
- /// Sha256("<namespace>:<rust-identifier>")[..8],
+ /// If a match is found, the instruction handler is called using the given instruction data
+ /// excluding the prepended discriminator bytes.
  ///
- /// where the namespace can be one type. "global" for a
- /// regular instruction.
- ///
- /// With this 8 byte identifier, Anchor performs method dispatch,
- /// matching the given 8 byte identifier to the associated method
- /// handler, which leads to user defined code being eventually invoked.
+ /// If no match is found, the fallback function is executed if it exists, or an error is
+ /// returned if it doesn't exist.
  fn dispatch<'info>(
  program_id: &Pubkey,
  accounts: &'info [AccountInfo<'info>],

lang/syn/src/codegen/program/entry.rs

@@ -25,17 +25,10 @@ pub fn generate(program: &Program) -> proc_macro2::TokenStream {
  /// The execution flow of the generated code can be roughly outlined:
  ///
  /// * Start program via the entrypoint.
- /// * Strip method identifier off the first 8 bytes of the instruction
- /// data and invoke the identified method. The method identifier
- /// is a variant of sighash. See docs.rs for `anchor_lang` for details.
- /// * If the method identifier is an IDL identifier, execute the IDL
- /// instructions, which are a special set of hardcoded instructions
- /// baked into every Anchor program. Then exit.
- /// * Otherwise, the method identifier is for a user defined
- /// instruction, i.e., one of the methods in the user defined
- /// `#[program]` module. Perform method dispatch, i.e., execute the
- /// big match statement mapping method identifier to method handler
- /// wrapper.
+ /// * Check whether the declared program id matches the input program
+ /// id. If it's not, return an error.
+ /// * Find and invoke the method based on whether the instruction data
+ /// starts with the method's discriminator.
  /// * Run the method handler wrapper. This wraps the code the user
  /// actually wrote, deserializing the accounts, constructing the
  /// context, invoking the user's code, and finally running the exit

ts/packages/anchor/src/coder/borsh/accounts.ts

@@ -107,9 +107,9 @@ export class BorshAccountsCoder<A extends string = string>
  }
 
  /**
- * Calculates and returns a unique 8 byte discriminator prepended to all anchor accounts.
+ * Get the unique discriminator prepended to all anchor accounts.
  *
- * @param name The name of the account to calculate the discriminator.
+ * @param name The name of the account to get the discriminator of.
  */
  public accountDiscriminator(name: string): Buffer {
  const account = this.idl.accounts?.find((acc) => acc.name === name);