feat: add priceFeedIdToTwapUpdateAccount and update docs

Author: tejasbadadare

target_chains/solana/sdk/js/pyth_solana_receiver/README.md

@@ -175,6 +175,50 @@ Price updates are relatively large and can take multiple transactions to post on
 You can reduce the size of the transaction payload by using `addPostPartiallyVerifiedPriceUpdates` instead of `addPostPriceUpdates`.
 This method does sacrifice some security however -- please see the method documentation for more details.
 
+### Post a TWAP price update
+
+TWAP prices updates are calculated using a pair of verifiable cumulative price updates per price feed (the "start" and "end" updates for the given time window), and then performing an averaging calculation on-chain to create the time-weighted average price.
+
+The flow of using verifying, posting, and consuming these prices are the same as standard price updates. Get the binary update data from Hermes or Benchmarks, verify the VAAs via the Wormhole contract, and post the VAAs to the Pyth receiver contract. After this, you can consume the calculated TWAP posted to the TwapUpdate account. You can also optionally close these ephemeral accounts after the TWAP has been consumed to save on rent.
+
+```typescript
+// Fetch the binary TWAP data from hermes or benchmarks. See Preliminaries section above for more info.
+const binary_data_array = ["UE5BV...khz609", "UE5BV...BAg8i6"];
+
+// Pass `closeUpdateAccounts: true` to automatically close the TWAP update accounts
+// after they're consumed
+const transactionBuilder = pythSolanaReceiver.newTransactionBuilder({
+  closeUpdateAccounts: false,
+});
+
+// Post the updates and calculate the TWAP
+await transactionBuilder.addPostTwapUpdates(binary_data_array);
+
+// You can now use the TWAP prices in subsequent instructions
+await transactionBuilder.addPriceConsumerInstructions(
+  async (
+    getTwapUpdateAccount: (priceFeedId: string) => PublicKey
+  ): Promise<InstructionWithEphemeralSigners[]> => {
+    // Generate instructions here that use the TWAP updates posted above.
+    // getTwaoUpdateAccount(<price feed id>) will give you the account for each TWAP update.
+    return [];
+  }
+);
+
+// Send the instructions in the builder in 1 or more transactions.
+// The builder will pack the instructions into transactions automatically.
+sendTransactions(
+  await transactionBuilder.buildVersionedTransactions({
+    computeUnitPriceMicroLamports: 100000,
+    tightComputeBudget: true,
+  }),
+  pythSolanaReceiver.connection,
+  pythSolanaReceiver.wallet
+);
+```
+
+See `examples/post_twap_update.ts` for a runnable example of posting a TWAP price update.
+
 ### Get Instructions
 
 The `PythTransactionBuilder` class used in the examples above helps craft transactions that update prices and then use them in successive instructions.

target_chains/solana/sdk/js/pyth_solana_receiver/examples/post_twap_update.ts

@@ -0,0 +1,94 @@
+import { Connection, Keypair, PublicKey } from "@solana/web3.js";
+import { InstructionWithEphemeralSigners, PythSolanaReceiver } from "../";
+import { Wallet } from "@coral-xyz/anchor";
+import fs from "fs";
+import os from "os";
+import { HermesClient } from "@pythnetwork/hermes-client";
+import { sendTransactions } from "@pythnetwork/solana-utils";
+
+// Get price feed ids from https://pyth.network/developers/price-feed-ids#pyth-evm-stable
+const SOL_PRICE_FEED_ID =
+  "0xef0d8b6fda2ceba41da15d4095d1da392a0d2f8ed0c6c7bc0f4cfac8c280b56d";
+const ETH_PRICE_FEED_ID =
+  "0xff61491a931112ddf1bd8147cd1b641375f79f5825126d665480874634fd0ace";
+
+let keypairFile = "";
+if (process.env["SOLANA_KEYPAIR"]) {
+  keypairFile = process.env["SOLANA_KEYPAIR"];
+} else {
+  keypairFile = `${os.homedir()}/.config/solana/id.json`;
+}
+
+async function main() {
+  const connection = new Connection("https://api.devnet.solana.com");
+  const keypair = await loadKeypairFromFile(keypairFile);
+  console.log(
+    `Sending transactions from account: ${keypair.publicKey.toBase58()}`
+  );
+  const wallet = new Wallet(keypair);
+  const pythSolanaReceiver = new PythSolanaReceiver({ connection, wallet });
+
+  // Get the TWAP update from hermes
+  const twapUpdateData = await getTwapUpdateData();
+  console.log(`Posting TWAP update: ${twapUpdateData}`);
+
+  // Similar to price updates, we'll keep closeUpdateAccounts = false for easy exploration
+  const transactionBuilder = pythSolanaReceiver.newTransactionBuilder({
+    closeUpdateAccounts: false,
+  });
+
+  // Post the TWAP updates to ephemeral accounts, one per price feed
+  await transactionBuilder.addPostTwapUpdates(twapUpdateData);
+  console.log(
+    "The SOL/USD TWAP update will get posted to:",
+    transactionBuilder.getTwapUpdateAccount(SOL_PRICE_FEED_ID).toBase58()
+  );
+
+  await transactionBuilder.addTwapConsumerInstructions(
+    async (
+      getTwapUpdateAccount: (priceFeedId: string) => PublicKey
+    ): Promise<InstructionWithEphemeralSigners[]> => {
+      // You can generate instructions here that use the TWAP updates posted above.
+      // getTwapUpdateAccount(<price feed id>) will give you the account you need.
+      return [];
+    }
+  );
+
+  // Send the instructions in the builder in 1 or more transactions
+  sendTransactions(
+    await transactionBuilder.buildVersionedTransactions({
+      computeUnitPriceMicroLamports: 100000,
+      tightComputeBudget: true,
+    }),
+    pythSolanaReceiver.connection,
+    pythSolanaReceiver.wallet
+  );
+}
+
+// Fetch TWAP update data from Hermes
+async function getTwapUpdateData() {
+  const hermesConnection = new HermesClient("https://hermes.pyth.network/", {});
+
+  // Request TWAP updates for the last hour (3600 seconds)
+  const response = await hermesConnection.getLatestTwapUpdates(
+    [SOL_PRICE_FEED_ID, ETH_PRICE_FEED_ID],
+    3600,
+    { encoding: "base64" }
+  );
+
+  return response.binary.data;
+}
+
+// Load a solana keypair from an id.json file
+async function loadKeypairFromFile(filePath: string): Promise<Keypair> {
+  try {
+    const keypairData = JSON.parse(
+      await fs.promises.readFile(filePath, "utf8")
+    );
+    return Keypair.fromSecretKey(Uint8Array.from(keypairData));
+  } catch (error) {
+    throw new Error(`Error loading keypair from file: ${error}`);
+  }
+}
+
+main();

target_chains/solana/sdk/js/pyth_solana_receiver/src/PythSolanaReceiver.ts

@@ -103,6 +103,7 @@ export class PythTransactionBuilder extends TransactionBuilder {
   readonly pythSolanaReceiver: PythSolanaReceiver;
   readonly closeInstructions: InstructionWithEphemeralSigners[];
   readonly priceFeedIdToPriceUpdateAccount: Record<string, PublicKey>;
+  readonly priceFeedIdToTwapUpdateAccount: Record<string, PublicKey>;
   readonly closeUpdateAccounts: boolean;
 
   constructor(
@@ -118,6 +119,7 @@ export class PythTransactionBuilder extends TransactionBuilder {
     this.pythSolanaReceiver = pythSolanaReceiver;
     this.closeInstructions = [];
     this.priceFeedIdToPriceUpdateAccount = {};
+    this.priceFeedIdToTwapUpdateAccount = {};
     this.closeUpdateAccounts = config.closeUpdateAccounts ?? true;
   }
 
@@ -227,7 +229,7 @@ export class PythTransactionBuilder extends TransactionBuilder {
     );
     this.closeInstructions.push(...closeInstructions);
     Object.assign(
-      this.priceFeedIdToPriceUpdateAccount,
+      this.priceFeedIdToTwapUpdateAccount,
       priceFeedIdToTwapUpdateAccount
     );
     this.addInstructions(postInstructions);
@@ -311,6 +313,46 @@ export class PythTransactionBuilder extends TransactionBuilder {
     );
   }
 
+  /**
+   * Add instructions that consume TWAP updates to the builder.
+   *
+   * @param getInstructions a function that given a mapping of price feed IDs to TWAP update accounts, generates a series of instructions. TWAP updates get posted to ephemeral accounts and this function allows the user to indicate which accounts in their instruction need to be "replaced" with each price update account.
+   * If multiple TWAP updates for the same price feed ID are posted with the same builder, the account corresponding to the last update to get posted will be used.
+   *
+   * @example
+   * ```typescript
+   * ...
+   * await transactionBuilder.addPostTwapUpdates(twapUpdateData);
+   * await transactionBuilder.addTwapConsumerInstructions(
+   *   async (
+   *     getTwapUpdateAccount: ( priceFeedId: string) => PublicKey
+   *   ): Promise<InstructionWithEphemeralSigners[]> => {
+   *     return [
+   *       {
+   *         instruction: await myFirstPythApp.methods
+   *           .consume()
+   *           .accounts({
+   *              solTwapUpdate: getTwapUpdateAccount(SOL_PRICE_FEED_ID),
+   *              ethTwapUpdate: getTwapUpdateAccount(ETH_PRICE_FEED_ID),
+   *           })
+   *           .instruction(),
+   *         signers: [],
+   *       },
+   *     ];
+   *   }
+   * );
+   * ```
+   */
+  async addTwapConsumerInstructions(
+    getInstructions: (
+      getTwapUpdateAccount: (priceFeedId: string) => PublicKey
+    ) => Promise<InstructionWithEphemeralSigners[]>
+  ) {
+    this.addInstructions(
+      await getInstructions(this.getTwapUpdateAccount.bind(this))
+    );
+  }
+
   /** Add instructions to close encoded VAA accounts from previous actions.
    * If you have previously used the PythTransactionBuilder with closeUpdateAccounts set to false or if you posted encoded VAAs but the transaction to close them did not land on-chain, your wallet might own many encoded VAA accounts.
    * The rent cost for these accounts is 0.008 SOL per encoded VAA account. You can recover this rent calling this function when building a set of transactions.
@@ -356,11 +398,25 @@ export class PythTransactionBuilder extends TransactionBuilder {
       this.priceFeedIdToPriceUpdateAccount[priceFeedId];
     if (!priceUpdateAccount) {
       throw new Error(
-        `No price update account found for the price feed ID ${priceFeedId}. Make sure to call addPostPriceUpdates or addPostPartiallyVerifiedPriceUpdates or postTwapUpdates before calling this function.`
+        `No price update account found for the price feed ID ${priceFeedId}. Make sure to call addPostPriceUpdates or addPostPartiallyVerifiedPriceUpdates before calling this function.`
       );
     }
     return priceUpdateAccount;
   }
+
+  /**
+   * This method is used to retrieve the address of the TWAP update account where the TWAP update for a given price feed ID will be posted.
+   * If multiple updates for the same price feed ID will be posted with the same builder, the address of the account corresponding to the last update to get posted will be returned.
+   * */
+  getTwapUpdateAccount(priceFeedId: string): PublicKey {
+    const twapUpdateAccount = this.priceFeedIdToTwapUpdateAccount[priceFeedId];
+    if (!twapUpdateAccount) {
+      throw new Error(
+        `No TWAP update account found for the price feed ID ${priceFeedId}. Make sure to call addPostTwapUpdates before calling this function.`
+      );
+    }
+    return twapUpdateAccount;
+  }
 }
 
 /**