docs: readme

Author: nickfrosty

.prettierrc

@@ -0,0 +1,11 @@
+{
+  "tabWidth": 2,
+  "useTabs": false,
+  "singleQuote": false,
+  "bracketSpacing": true,
+  "semi": true,
+  "trailingComma": "all",
+  "proseWrap": "always",
+  "arrowParens": "always",
+  "printWidth": 100
+}

.prettierrc.json

@@ -1,6 +1,17 @@
-# Solana helpers
+# Solana web3.js v1 helpers
 
-The `helpers` package contains Solana helper functions, for use in the browser and/or node.js, [made by the Solana Foundation Developer Ecosystem team](https://youtu.be/zvQIa68ObK8?t=319) and our friends at [Anza](https://anza.xyz), [Turbin3](https://turbin3.com/), [Unboxed Software](https://beunboxed.com/), and [StarAtlas](https://staratlas.com/).
+The `@solana-developers/helpers` package contains Solana helper functions, for use in the browser
+and/or node.js, made by the Solana Foundation's
+[Developer Relations team](https://x.com/solana_devs) and contributions from
+[Anza](https://anza.xyz), [Turbin3](https://turbin3.com/),
+[Unboxed Software](https://beunboxed.com/), and [StarAtlas](https://staratlas.com/).
+
+> [!IMPORTANT]  
+> `@solana-developers/helpers` is for Solana web3.js version 1. The updated version of this package
+> which is compatible with Solana web3.js version 2 is called `gill`. Learn more here:
+>
+> - npm registry - https://www.npmjs.com/package/gill
+> - source repository - https://github.com/solana-foundation/gill
 
 ## What can I do with this module?
 
@@ -33,6 +44,7 @@ The `helpers` package contains Solana helper functions, for use in the browser a
 [Get an airdrop if your balance is below some amount](#get-an-airdrop-if-your-balance-is-below-some-amount)
 
 ### Error Handling & Utilities:
+
 [Resolve a custom error message](#resolve-a-custom-error-message)
 
 [Get a Solana Explorer link for a transaction, address, or block](#get-a-solana-explorer-link-for-a-transaction-address-or-block)
@@ -53,9 +65,11 @@ npm i @solana-developers/helpers
 
 ## Contributing
 
-PRs are very much welcome! Read the [CONTRIBUTING guidelines for the Solana course](https://github.com/Unboxed-Software/solana-course/blob/main/CONTRIBUTING.md#code) then send a PR!
+PRs are very much welcome! Read the
+[CONTRIBUTING guidelines for the Solana course](https://github.com/Unboxed-Software/solana-course/blob/main/CONTRIBUTING.md#code)
+then send a PR!
 
-## helpers for the browser and node.js
+## Helpers for the browser and node.js
 
 ### Make multiple keypairs at once
 
@@ -65,17 +79,22 @@ Usage:
 makeKeypairs(amount);
 ```
 
-In some situations - like making tests for your onchain programs - you might need to make lots of keypairs at once. You can use `makeKeypairs()` combined with JS destructuring to quickly create multiple variables with distinct keypairs.
+In some situations - like making tests for your onchain programs - you might need to make lots of
+keypairs at once. You can use `makeKeypairs()` combined with JS destructuring to quickly create
+multiple variables with distinct keypairs.
 
 ```typescript
 const [sender, recipient] = makeKeypairs(2);
 ```
 
 ### Make a token mint with metadata
 
-The `makeTokenMint` makes a new token mint. A token mint is effectively the factory that produces token of a particular type. So if you want to make a new token, this is the right function for you!
+The `makeTokenMint` makes a new token mint. A token mint is effectively the factory that produces
+token of a particular type. So if you want to make a new token, this is the right function for you!
 
-Unlike older tools, the function uses Token Extensions Metadata and Metadata Pointer to put all metadata into the Mint Account, without needing an external Metadata account. If you don't know what that means, just know that things are simpler than they used to be!
+Unlike older tools, the function uses Token Extensions Metadata and Metadata Pointer to put all
+metadata into the Mint Account, without needing an external Metadata account. If you don't know what
+that means, just know that things are simpler than they used to be!
 
 Parameters
 
@@ -85,7 +104,8 @@ Parameters
 - `symbol`: string, like a ticker symbol. Usually in all-caps.
 - `decimals`: number, how many decimal places the new token will have.
 - `uri`: string, URI to a JSON file containing at minimum a value for `image`.
-- `additionalMetadata`: additional metadata as either `Record<string, string>` or `Array<[string, string]>`(optional).
+- `additionalMetadata`: additional metadata as either `Record<string, string>` or
+  `Array<[string, string]>`(optional).
 - `updateAuthority`: PublicKey (optional) - public key of the account that can update the token.
 - `freezeAuthority`: PublicKey (optional) - public key of the freeze account, default to `null`
 
@@ -102,7 +122,10 @@ const mintAddress = await makeTokenMint(
 
 ### Create users, mints and token accounts in a single step
 
-Frequently, tests for onchain programs need to make not just users with SOL, but also token mints and give each user some balance of each token. To save this boilerplate, `createAccountsMintsAndTokenAccounts()` handles making user keypairs, giving them SOL, making mints, creating associated token accounts, and minting tokens directly to the associated token accounts.
+Frequently, tests for onchain programs need to make not just users with SOL, but also token mints
+and give each user some balance of each token. To save this boilerplate,
+`createAccountsMintsAndTokenAccounts()` handles making user keypairs, giving them SOL, making mints,
+creating associated token accounts, and minting tokens directly to the associated token accounts.
 
 Eg, to make two new users, and two tokens:
 
@@ -133,7 +156,8 @@ The returned `usersMintsAndTokenAccounts` will be an object of the form:
 }
 ```
 
-tokenAccounts are indexed by the user, then the mint. Eg, the ATA of `user[0]` for `mint[0]` is `tokenAccounts[0][0]`.
+tokenAccounts are indexed by the user, then the mint. Eg, the ATA of `user[0]` for `mint[0]` is
+`tokenAccounts[0][0]`.
 
 ### Resolve a custom error message
 
@@ -145,7 +169,8 @@ getCustomErrorMessage(programErrors, errorMessage);
 
 Sometimes Solana transactions throw an error with a message like:
 
-> failed to send transaction: Transaction simulation failed: Error processing Instruction 0: custom program error: 0x10
+> failed to send transaction: Transaction simulation failed: Error processing Instruction 0: custom
+> program error: 0x10
 
 Usage:
 
@@ -159,7 +184,8 @@ Allows you to turn this message into a more readable message from the custom pro
 
 Just:
 
-- Get the errors from the specific program's `error.rs` file - for example, there are [the errors for the Token Program](https://github.com/solana-labs/solana-program-library/blob/master/token/program/src/error.rs)
+- Get the errors from the specific program's `error.rs` file - for example, there are
+  [the errors for the Token Program](https://github.com/solana-labs/solana-program-library/blob/master/token/program/src/error.rs)
 
 - Save the errors into an array
 
@@ -213,7 +239,10 @@ Usage:
 airdropIfRequired(connection, publicKey, lamports, maximumBalance);
 ```
 
-Request and confirm an airdrop in one step. As soon as the `await` returns, the airdropped tokens will be ready to use, and the new balance of tokens will be returned. The `maximumBalance` is used to avoid errors caused by unnecessarily asking for SOL when there's already enough in the account, and makes `airdropIfRequired()` very handy in scripts that run repeatedly.
+Request and confirm an airdrop in one step. As soon as the `await` returns, the airdropped tokens
+will be ready to use, and the new balance of tokens will be returned. The `maximumBalance` is used
+to avoid errors caused by unnecessarily asking for SOL when there's already enough in the account,
+and makes `airdropIfRequired()` very handy in scripts that run repeatedly.
 
 To ask for 0.5 SOL, if the balance is below 1 SOL, use:
 
@@ -237,24 +266,18 @@ getExplorerLink(type, identifier, clusterName);
 Get an explorer link for an `address`, `block` or `transaction` (`tx` works too).
 
 ```typescript
-getExplorerLink(
-  "address",
-  "dDCQNnDmNbFVi8cQhKAgXhyhXeJ625tvwsunRyRc7c8",
-  "mainnet-beta",
-);
+getExplorerLink("address", "dDCQNnDmNbFVi8cQhKAgXhyhXeJ625tvwsunRyRc7c8", "mainnet-beta");
 ```
 
-Will return `"https://explorer.solana.com/address/dDCQNnDmNbFVi8cQhKAgXhyhXeJ625tvwsunRyRc7c8"`. The cluster name isn't included since mainnet-beta is the default.
+Will return `"https://explorer.solana.com/address/dDCQNnDmNbFVi8cQhKAgXhyhXeJ625tvwsunRyRc7c8"`. The
+cluster name isn't included since mainnet-beta is the default.
 
 ```typescript
-getExplorerLink(
-  "address",
-  "dDCQNnDmNbFVi8cQhKAgXhyhXeJ625tvwsunRyRc7c8",
-  "devnet",
-);
+getExplorerLink("address", "dDCQNnDmNbFVi8cQhKAgXhyhXeJ625tvwsunRyRc7c8", "devnet");
 ```
 
-Will return `"https://explorer.solana.com/address/dDCQNnDmNbFVi8cQhKAgXhyhXeJ625tvwsunRyRc7c8?cluster=devnet"`
+Will return
+`"https://explorer.solana.com/address/dDCQNnDmNbFVi8cQhKAgXhyhXeJ625tvwsunRyRc7c8?cluster=devnet"`
 
 ```typescript
 getExplorerLink("block", "241889720", "mainnet-beta");
@@ -322,14 +345,13 @@ const sendSol = SystemProgram.transfer({
 Then use `getSimulationComputeUnits` to get the number of compute units the instructions will use:
 
 ```typescript
-const units = await getSimulationComputeUnits(
-  connection,
-  [sendSol],
-  payer.publicKey,
-);
+const units = await getSimulationComputeUnits(connection, [sendSol], payer.publicKey);
 ```
 
-You can then use `ComputeBudgetProgram.setComputeUnitLimit({ units })` as the first instruction in your transaction. See [How to Request Optimal Compute Budget](https://solana.com/developers/guides/advanced/how-to-request-optimal-compute) for more information on compute units.
+You can then use `ComputeBudgetProgram.setComputeUnitLimit({ units })` as the first instruction in
+your transaction. See
+[How to Request Optimal Compute Budget](https://solana.com/developers/guides/advanced/how-to-request-optimal-compute)
+for more information on compute units.
 
 ### `addComputeInstructions`
 
@@ -358,7 +380,7 @@ This function:
 3. Adds compute unit limit instruction with buffer
 4. Returns the updated instructions array
 
-## node.js specific helpers
+## Node.js specific helpers
 
 ### Get a keypair from a keypair file
 
@@ -368,7 +390,8 @@ Usage:
 getKeypairFromFile(filename);
 ```
 
-Gets a keypair from a file - the format must be the same as [Solana CLI](https://docs.solana.com/wallet-guide/file-system-wallet) uses, ie, a JSON array of numbers:
+Gets a keypair from a file - the format must be the same as
+[Solana CLI](https://docs.anza.xyz/cli/wallets/file-system) uses, ie, a JSON array of numbers:
 
 To load the default keypair `~/.config/solana/id.json`, just run:
 
@@ -396,7 +419,9 @@ Usage:
 getKeypairFromEnvironment(environmentVariable);
 ```
 
-Gets a keypair from a secret key stored in an environment variable. This is typically used to load secret keys from [env files](https://stackoverflow.com/questions/68267862/what-is-an-env-or-dotenv-file-exactly).
+Gets a keypair from a secret key stored in an environment variable. This is typically used to load
+secret keys from
+[env files](https://stackoverflow.com/questions/68267862/what-is-an-env-or-dotenv-file-exactly).
 
 ```typescript
 const keypair = await getKeypairFromEnvironment("SECRET_KEY");
@@ -446,11 +471,15 @@ interface initializeKeypairOptions {
 }
 ```
 
-By default, the keypair will be retrieved from the `.env` file. If a `.env` file does not exist, this function will create one with a new keypair under the optional `envVariableName`.
+By default, the keypair will be retrieved from the `.env` file. If a `.env` file does not exist,
+this function will create one with a new keypair under the optional `envVariableName`.
 
-To load the keypair from the filesystem, pass in the `keypairPath`. When set, loading a keypair from the filesystem will take precedence over loading from the `.env` file.
+To load the keypair from the filesystem, pass in the `keypairPath`. When set, loading a keypair from
+the filesystem will take precedence over loading from the `.env` file.
 
-If `airdropAmount` amount is set to something other than `null` or `0`, this function will then check the account's balance. If the balance is below the `minimumBalance`, it will airdrop the account `airdropAmount`.
+If `airdropAmount` amount is set to something other than `null` or `0`, this function will then
+check the account's balance. If the balance is below the `minimumBalance`, it will airdrop the
+account `airdropAmount`.
 
 To initialize a keypair from the `.env` file, and airdrop it 1 sol if it's beneath 0.5 sol:
 
@@ -485,7 +514,8 @@ const DEFAULT_ENV_KEYPAIR_VARIABLE_NAME = "PRIVATE_KEY";
 
 ## Secret key format
 
-Secret keys can be read in either the more compact base58 format (`base58.encode(randomKeypair.secretKey);`), like:
+Secret keys can be read in either the more compact base58 format
+(`base58.encode(randomKeypair.secretKey);`), like:
 
 ```bash
 # A random secret key for demo purposes
@@ -499,7 +529,8 @@ Or the longer, 'array of numbers' format `JSON.stringify(Object.values(randomKey
 SECRET_KEY=[112,222,91,246,55,109,221,4,23,148,251,127,212,180,44,249,182,139,18,13,209,208,6,7,193,210,186,249,148,237,237,1,70,118,1,153,238,134,239,75,187,96,101,138,147,130,181,71,22,82,44,217,194,122,59,208,134,119,98,53,136,108,44,105]
 ```
 
-We always save keys using the 'array of numbers' format, since most other Solana apps (like the CLI SDK and Rust tools) use the 'array of numbers' format.
+We always save keys using the 'array of numbers' format, since most other Solana apps (like the CLI
+SDK and Rust tools) use the 'array of numbers' format.
 
 ## Development
 
@@ -515,7 +546,8 @@ Then in a different tab, run:
 npm run test
 ```
 
-The tests use the [node native test runner](https://blog.logrocket.com/exploring-node-js-native-test-runner/).
+The tests use the
+[node native test runner](https://blog.logrocket.com/exploring-node-js-native-test-runner/).
 
 If you'd like to run a single test, use:
 
@@ -569,8 +601,10 @@ The function will:
 For RPC providers that support priority fees:
 
 - Helius: minimum 10000 microLamports
-- Triton: see their [priority fee API](https://docs.triton.one/chains/solana/improved-priority-fees-api)
-- Quicknode: see their [priority fee estimation](https://www.quicknode.com/docs/solana/qn_estimatePriorityFees)
+- Triton: see their
+  [priority fee API](https://docs.triton.one/chains/solana/improved-priority-fees-api)
+- Quicknode: see their
+  [priority fee estimation](https://www.quicknode.com/docs/solana/qn_estimatePriorityFees)
 
 #### `sendVersionedTransaction`
 
@@ -621,11 +655,11 @@ async function createLookupTable(
 Example:
 
 ```typescript
-const [lookupTableAddress, lookupTableAccount] = await createLookupTable(
-  connection,
-  payer,
-  [account1.publicKey, account2.publicKey, account3.publicKey],
-);
+const [lookupTableAddress, lookupTableAccount] = await createLookupTable(connection, payer, [
+  account1.publicKey,
+  account2.publicKey,
+  account3.publicKey,
+]);
 // Can either cache the lookup table address and lookup table account for reuse, or use them directly
 const signature = await sendVersionedTransaction(
   connection,
@@ -671,17 +705,13 @@ Usage:
 
 ```typescript
 const idl = await getIdlByProgramId(programId, connection);
-const data = await getIdlParsedAccountData(
-  idl,
-  "counter",
-  accountAddress,
-  connection,
-);
+const data = await getIdlParsedAccountData(idl, "counter", accountAddress, connection);
 
 // Decoded Data: { count: <BN: 2> }
 ```
 
-Fetches and parses an account's data using an Anchor IDL file. This is useful when you need to decode account data from Anchor programs.
+Fetches and parses an account's data using an Anchor IDL file. This is useful when you need to
+decode account data from Anchor programs.
 
 ### Parse Transaction Events
 
@@ -698,7 +728,8 @@ const events = await parseAnchorTransactionEvents(idl, signature, connection);
 // }
 ```
 
-Parses all Anchor events emitted in a transaction. This helps you track and verify program events after transaction execution.
+Parses all Anchor events emitted in a transaction. This helps you track and verify program events
+after transaction execution.
 
 ### Decode Anchor Transaction