@solana/web3.js 0.0.0-next → 0.0.0-pr-29130

package/src/{transaction.ts → transaction/legacy.ts}

@@ -1,39 +1,34 @@
-import nacl from 'tweetnacl';
 import bs58 from 'bs58';
 import {Buffer} from 'buffer';
 
-import {Connection} from './connection';
-import {Message} from './message';
-import {PublicKey} from './publickey';
-import * as shortvec from './util/shortvec-encoding';
-import {toBuffer} from './util/to-buffer';
-import invariant from './util/assert';
-import type {Signer} from './keypair';
-import type {Blockhash} from './blockhash';
-import type {CompiledInstruction} from './message';
+import {PACKET_DATA_SIZE, SIGNATURE_LENGTH_IN_BYTES} from './constants';
+import {Connection} from '../connection';
+import {Message} from '../message';
+import {PublicKey} from '../publickey';
+import * as shortvec from '../utils/shortvec-encoding';
+import {toBuffer} from '../utils/to-buffer';
+import invariant from '../utils/assert';
+import type {Signer} from '../keypair';
+import type {Blockhash} from '../blockhash';
+import type {CompiledInstruction} from '../message';
+import {sign, verify} from '../utils/ed25519';
 
 /**
  * Transaction signature as base-58 encoded string
  */
 export type TransactionSignature = string;
 
-/**
- * Default (empty) signature
- *
- * Signatures are 64 bytes in length
- */
-const DEFAULT_SIGNATURE = Buffer.alloc(64).fill(0);
+export const enum TransactionStatus {
+  BLOCKHEIGHT_EXCEEDED,
+  PROCESSED,
+  TIMED_OUT,
+  NONCE_INVALID,
+}
 
 /**
- * Maximum over-the-wire size of a Transaction
- *
- * 1280 is IPv6 minimum MTU
- * 40 bytes is the size of the IPv6 header
- * 8 bytes is the size of the fragment header
+ * Default (empty) signature
  */
-export const PACKET_DATA_SIZE = 1280 - 40 - 8;
-
-const SIGNATURE_LENGTH = 64;
+const DEFAULT_SIGNATURE = Buffer.alloc(SIGNATURE_LENGTH_IN_BYTES).fill(0);
 
 /**
  * Account metadata used to define instructions
@@ -133,17 +128,49 @@ export type SignaturePubkeyPair = {
 
 /**
  * List of Transaction object fields that may be initialized at construction
- *
  */
-export type TransactionCtorFields = {
-  /** A recent blockhash */
-  recentBlockhash?: Blockhash | null;
+export type TransactionCtorFields_DEPRECATED = {
   /** Optional nonce information used for offline nonce'd transactions */
   nonceInfo?: NonceInformation | null;
   /** The transaction fee payer */
   feePayer?: PublicKey | null;
   /** One or more signatures */
   signatures?: Array<SignaturePubkeyPair>;
+  /** A recent blockhash */
+  recentBlockhash?: Blockhash;
+};
+
+// For backward compatibility; an unfortunate consequence of being
+// forced to over-export types by the documentation generator.
+// See https://github.com/solana-labs/solana/pull/25820
+export type TransactionCtorFields = TransactionCtorFields_DEPRECATED;
+
+/**
+ * Blockhash-based transactions have a lifetime that are defined by
+ * the blockhash they include. Any transaction whose blockhash is
+ * too old will be rejected.
+ */
+export type TransactionBlockhashCtor = {
+  /** The transaction fee payer */
+  feePayer?: PublicKey | null;
+  /** One or more signatures */
+  signatures?: Array<SignaturePubkeyPair>;
+  /** A recent blockhash */
+  blockhash: Blockhash;
+  /** the last block chain can advance to before tx is declared expired */
+  lastValidBlockHeight: number;
+};
+
+/**
+ * Use these options to construct a durable nonce transaction.
+ */
+export type TransactionNonceCtor = {
+  /** The transaction fee payer */
+  feePayer?: PublicKey | null;
+  minContextSlot: number;
+  nonceInfo: NonceInformation;
+  /** One or more signatures */
+  signatures?: Array<SignaturePubkeyPair>;
 };
 
 /**
@@ -205,12 +232,26 @@ export class Transaction {
    */
   recentBlockhash?: Blockhash;
 
+  /**
+   * the last block chain can advance to before tx is declared expired
+   * */
+  lastValidBlockHeight?: number;
+
   /**
    * Optional Nonce information. If populated, transaction will use a durable
    * Nonce hash instead of a recentBlockhash. Must be populated by the caller
    */
   nonceInfo?: NonceInformation;
 
+  /**
+   * If this is a nonce transaction this represents the minimum slot from which
+   * to evaluate if the nonce has advanced when attempting to confirm the
+   * transaction. This protects against a case where the transaction confirmation
+   * logic loads the nonce account from an old slot and assumes the mismatch in
+   * nonce value implies that the nonce has been advanced.
+   */
+  minNonceContextSlot?: number;
+
   /**
    * @internal
    */
@@ -221,11 +262,55 @@ export class Transaction {
    */
   _json?: TransactionJSON;
 
+  // Construct a transaction with a blockhash and lastValidBlockHeight
+  constructor(opts?: TransactionBlockhashCtor);
+
+  // Construct a transaction using a durable nonce
+  constructor(opts?: TransactionNonceCtor);
+
+  /**
+   * @deprecated `TransactionCtorFields` has been deprecated and will be removed in a future version.
+   * Please supply a `TransactionBlockhashCtor` instead.
+   */
+  constructor(opts?: TransactionCtorFields_DEPRECATED);
+
   /**
    * Construct an empty Transaction
    */
-  constructor(opts?: TransactionCtorFields) {
-    opts && Object.assign(this, opts);
+  constructor(
+    opts?:
+      | TransactionBlockhashCtor
+      | TransactionNonceCtor
+      | TransactionCtorFields_DEPRECATED,
+  ) {
+    if (!opts) {
+      return;
+    }
+    if (opts.feePayer) {
+      this.feePayer = opts.feePayer;
+    }
+    if (opts.signatures) {
+      this.signatures = opts.signatures;
+    }
+    if (Object.prototype.hasOwnProperty.call(opts, 'nonceInfo')) {
+      const {minContextSlot, nonceInfo} = opts as TransactionNonceCtor;
+      this.minNonceContextSlot = minContextSlot;
+      this.nonceInfo = nonceInfo;
+    } else if (
+      Object.prototype.hasOwnProperty.call(opts, 'lastValidBlockHeight')
+    ) {
+      const {blockhash, lastValidBlockHeight} =
+        opts as TransactionBlockhashCtor;
+      this.recentBlockhash = blockhash;
+      this.lastValidBlockHeight = lastValidBlockHeight;
+    } else {
+      const {recentBlockhash, nonceInfo} =
+        opts as TransactionCtorFields_DEPRECATED;
+      if (nonceInfo) {
+        this.nonceInfo = nonceInfo;
+      }
+      this.recentBlockhash = recentBlockhash;
+    }
   }
 
   /**
@@ -276,26 +361,31 @@ export class Transaction {
    * Compile transaction data
    */
   compileMessage(): Message {
-    if (this._message) {
-      if (JSON.stringify(this.toJSON()) !== JSON.stringify(this._json)) {
-        throw new Error(
-          'Transaction message mutated after being populated from Message',
-        );
-      }
+    if (
+      this._message &&
+      JSON.stringify(this.toJSON()) === JSON.stringify(this._json)
+    ) {
       return this._message;
     }
 
-    const {nonceInfo} = this;
-    if (nonceInfo && this.instructions[0] != nonceInfo.nonceInstruction) {
-      this.recentBlockhash = nonceInfo.nonce;
-      this.instructions.unshift(nonceInfo.nonceInstruction);
+    let recentBlockhash;
+    let instructions: TransactionInstruction[];
+    if (this.nonceInfo) {
+      recentBlockhash = this.nonceInfo.nonce;
+      if (this.instructions[0] != this.nonceInfo.nonceInstruction) {
+        instructions = [this.nonceInfo.nonceInstruction, ...this.instructions];
+      } else {
+        instructions = this.instructions;
+      }
+    } else {
+      recentBlockhash = this.recentBlockhash;
+      instructions = this.instructions;
     }
-    const {recentBlockhash} = this;
     if (!recentBlockhash) {
       throw new Error('Transaction recentBlockhash required');
     }
 
-    if (this.instructions.length < 1) {
+    if (instructions.length < 1) {
       console.warn('No instructions provided');
     }
 
@@ -309,8 +399,8 @@ export class Transaction {
       throw new Error('Transaction fee payer required');
     }
 
-    for (let i = 0; i < this.instructions.length; i++) {
-      if (this.instructions[i].programId === undefined) {
+    for (let i = 0; i < instructions.length; i++) {
+      if (instructions[i].programId === undefined) {
         throw new Error(
           `Transaction instruction index ${i} has undefined program id`,
         );
@@ -319,7 +409,7 @@ export class Transaction {
 
     const programIds: string[] = [];
     const accountMetas: AccountMeta[] = [];
-    this.instructions.forEach(instruction => {
+    instructions.forEach(instruction => {
       instruction.keys.forEach(accountMeta => {
         accountMetas.push({...accountMeta});
       });
@@ -339,17 +429,6 @@ export class Transaction {
       });
     });
 
-    // Sort. Prioritizing first by signer, then by writable
-    accountMetas.sort(function (x, y) {
-      const pubkeySorting = x.pubkey
-        .toBase58()
-        .localeCompare(y.pubkey.toBase58());
-      const checkSigner = x.isSigner === y.isSigner ? 0 : x.isSigner ? -1 : 1;
-      const checkWritable =
-        x.isWritable === y.isWritable ? pubkeySorting : x.isWritable ? -1 : 1;
-      return checkSigner || checkWritable;
-    });
-
     // Cull duplicate account metas
     const uniqueMetas: AccountMeta[] = [];
     accountMetas.forEach(accountMeta => {
@@ -360,11 +439,27 @@ export class Transaction {
       if (uniqueIndex > -1) {
         uniqueMetas[uniqueIndex].isWritable =
           uniqueMetas[uniqueIndex].isWritable || accountMeta.isWritable;
+        uniqueMetas[uniqueIndex].isSigner =
+          uniqueMetas[uniqueIndex].isSigner || accountMeta.isSigner;
       } else {
         uniqueMetas.push(accountMeta);
       }
     });
 
+    // Sort. Prioritizing first by signer, then by writable
+    uniqueMetas.sort(function (x, y) {
+      if (x.isSigner !== y.isSigner) {
+        // Signers always come before non-signers
+        return x.isSigner ? -1 : 1;
+      }
+      if (x.isWritable !== y.isWritable) {
+        // Writable accounts always come before read-only accounts
+        return x.isWritable ? -1 : 1;
+      }
+      // Otherwise, sort by pubkey, stringwise.
+      return x.pubkey.toBase58().localeCompare(y.pubkey.toBase58());
+    });
+
     // Move fee payer to the front
     const feePayerIndex = uniqueMetas.findIndex(x => {
       return x.pubkey.equals(feePayer);
@@ -424,7 +519,7 @@ export class Transaction {
     });
 
     const accountKeys = signedKeys.concat(unsignedKeys);
-    const instructions: CompiledInstruction[] = this.instructions.map(
+    const compiledInstructions: CompiledInstruction[] = instructions.map(
       instruction => {
         const {data, programId} = instruction;
         return {
@@ -437,7 +532,7 @@ export class Transaction {
       },
     );
 
-    instructions.forEach(instruction => {
+    compiledInstructions.forEach(instruction => {
       invariant(instruction.programIdIndex >= 0);
       instruction.accounts.forEach(keyIndex => invariant(keyIndex >= 0));
     });
@@ -450,7 +545,7 @@ export class Transaction {
       },
       accountKeys,
       recentBlockhash,
-      instructions,
+      instructions: compiledInstructions,
     });
   }
 
@@ -562,7 +657,6 @@ export class Transaction {
 
     const message = this._compile();
     this._partialSign(message, ...uniqueSigners);
-    this._verifySignatures(message.serialize(), true);
   }
 
   /**
@@ -600,7 +694,7 @@ export class Transaction {
   _partialSign(message: Message, ...signers: Array<Signer>) {
     const signData = message.serialize();
     signers.forEach(signer => {
-      const signature = nacl.sign.detached(signData, signer.secretKey);
+      const signature = sign(signData, signer.secretKey);
       this._addSignature(signer.publicKey, toBuffer(signature));
     });
   }
@@ -641,16 +735,17 @@ export class Transaction {
   /**
    * @internal
    */
-  _verifySignatures(signData: Buffer, requireAllSignatures: boolean): boolean {
+  _verifySignatures(
+    signData: Uint8Array,
+    requireAllSignatures: boolean,
+  ): boolean {
     for (const {signature, publicKey} of this.signatures) {
       if (signature === null) {
         if (requireAllSignatures) {
           return false;
         }
       } else {
-        if (
-          !nacl.sign.detached.verify(signData, signature, publicKey.toBuffer())
-        ) {
+        if (!verify(signature, signData, publicKey.toBytes())) {
           return false;
         }
       }
@@ -747,8 +842,8 @@ export class Transaction {
     const signatureCount = shortvec.decodeLength(byteArray);
     let signatures = [];
     for (let i = 0; i < signatureCount; i++) {
-      const signature = byteArray.slice(0, SIGNATURE_LENGTH);
-      byteArray = byteArray.slice(SIGNATURE_LENGTH);
+      const signature = byteArray.slice(0, SIGNATURE_LENGTH_IN_BYTES);
+      byteArray = byteArray.slice(SIGNATURE_LENGTH_IN_BYTES);
       signatures.push(bs58.encode(Buffer.from(signature)));
     }
 

package/src/transaction/message.ts

@@ -0,0 +1,140 @@
+import {AccountKeysFromLookups} from '../message/account-keys';
+import assert from '../utils/assert';
+import {toBuffer} from '../utils/to-buffer';
+import {Blockhash} from '../blockhash';
+import {Message, MessageV0, VersionedMessage} from '../message';
+import {PublicKey} from '../publickey';
+import {AddressLookupTableAccount} from '../programs';
+import {AccountMeta, TransactionInstruction} from './legacy';
+
+export type TransactionMessageArgs = {
+  payerKey: PublicKey;
+  instructions: Array<TransactionInstruction>;
+  recentBlockhash: Blockhash;
+};
+
+export type DecompileArgs =
+  | {
+      accountKeysFromLookups: AccountKeysFromLookups;
+    }
+  | {
+      addressLookupTableAccounts: AddressLookupTableAccount[];
+    };
+
+export class TransactionMessage {
+  payerKey: PublicKey;
+  instructions: Array<TransactionInstruction>;
+  recentBlockhash: Blockhash;
+
+  constructor(args: TransactionMessageArgs) {
+    this.payerKey = args.payerKey;
+    this.instructions = args.instructions;
+    this.recentBlockhash = args.recentBlockhash;
+  }
+
+  static decompile(
+    message: VersionedMessage,
+    args?: DecompileArgs,
+  ): TransactionMessage {
+    const {header, compiledInstructions, recentBlockhash} = message;
+
+    const {
+      numRequiredSignatures,
+      numReadonlySignedAccounts,
+      numReadonlyUnsignedAccounts,
+    } = header;
+
+    const numWritableSignedAccounts =
+      numRequiredSignatures - numReadonlySignedAccounts;
+    assert(numWritableSignedAccounts > 0, 'Message header is invalid');
+
+    const numWritableUnsignedAccounts =
+      message.staticAccountKeys.length -
+      numRequiredSignatures -
+      numReadonlyUnsignedAccounts;
+    assert(numWritableUnsignedAccounts >= 0, 'Message header is invalid');
+
+    const accountKeys = message.getAccountKeys(args);
+    const payerKey = accountKeys.get(0);
+    if (payerKey === undefined) {
+      throw new Error(
+        'Failed to decompile message because no account keys were found',
+      );
+    }
+
+    const instructions: TransactionInstruction[] = [];
+    for (const compiledIx of compiledInstructions) {
+      const keys: AccountMeta[] = [];
+
+      for (const keyIndex of compiledIx.accountKeyIndexes) {
+        const pubkey = accountKeys.get(keyIndex);
+        if (pubkey === undefined) {
+          throw new Error(
+            `Failed to find key for account key index ${keyIndex}`,
+          );
+        }
+
+        const isSigner = keyIndex < numRequiredSignatures;
+
+        let isWritable;
+        if (isSigner) {
+          isWritable = keyIndex < numWritableSignedAccounts;
+        } else if (keyIndex < accountKeys.staticAccountKeys.length) {
+          isWritable =
+            keyIndex - numRequiredSignatures < numWritableUnsignedAccounts;
+        } else {
+          isWritable =
+            keyIndex - accountKeys.staticAccountKeys.length <
+            // accountKeysFromLookups cannot be undefined because we already found a pubkey for this index above
+            accountKeys.accountKeysFromLookups!.writable.length;
+        }
+
+        keys.push({
+          pubkey,
+          isSigner: keyIndex < header.numRequiredSignatures,
+          isWritable,
+        });
+      }
+
+      const programId = accountKeys.get(compiledIx.programIdIndex);
+      if (programId === undefined) {
+        throw new Error(
+          `Failed to find program id for program id index ${compiledIx.programIdIndex}`,
+        );
+      }
+
+      instructions.push(
+        new TransactionInstruction({
+          programId,
+          data: toBuffer(compiledIx.data),
+          keys,
+        }),
+      );
+    }
+
+    return new TransactionMessage({
+      payerKey,
+      instructions,
+      recentBlockhash,
+    });
+  }
+
+  compileToLegacyMessage(): Message {
+    return Message.compile({
+      payerKey: this.payerKey,
+      recentBlockhash: this.recentBlockhash,
+      instructions: this.instructions,
+    });
+  }
+
+  compileToV0Message(
+    addressLookupTableAccounts?: AddressLookupTableAccount[],
+  ): MessageV0 {
+    return MessageV0.compile({
+      payerKey: this.payerKey,
+      recentBlockhash: this.recentBlockhash,
+      instructions: this.instructions,
+      addressLookupTableAccounts,
+    });
+  }
+}

package/src/transaction/versioned.ts

@@ -0,0 +1,126 @@
+import * as BufferLayout from '@solana/buffer-layout';
+
+import {Signer} from '../keypair';
+import assert from '../utils/assert';
+import {VersionedMessage} from '../message/versioned';
+import {SIGNATURE_LENGTH_IN_BYTES} from './constants';
+import * as shortvec from '../utils/shortvec-encoding';
+import * as Layout from '../layout';
+import {sign} from '../utils/ed25519';
+import {PublicKey} from '../publickey';
+
+export type TransactionVersion = 'legacy' | 0;
+
+/**
+ * Versioned transaction class
+ */
+export class VersionedTransaction {
+  signatures: Array<Uint8Array>;
+  message: VersionedMessage;
+
+  get version(): TransactionVersion {
+    return this.message.version;
+  }
+
+  constructor(message: VersionedMessage, signatures?: Array<Uint8Array>) {
+    if (signatures !== undefined) {
+      assert(
+        signatures.length === message.header.numRequiredSignatures,
+        'Expected signatures length to be equal to the number of required signatures',
+      );
+      this.signatures = signatures;
+    } else {
+      const defaultSignatures = [];
+      for (let i = 0; i < message.header.numRequiredSignatures; i++) {
+        defaultSignatures.push(new Uint8Array(SIGNATURE_LENGTH_IN_BYTES));
+      }
+      this.signatures = defaultSignatures;
+    }
+    this.message = message;
+  }
+
+  serialize(): Uint8Array {
+    const serializedMessage = this.message.serialize();
+
+    const encodedSignaturesLength = Array<number>();
+    shortvec.encodeLength(encodedSignaturesLength, this.signatures.length);
+
+    const transactionLayout = BufferLayout.struct<{
+      encodedSignaturesLength: Uint8Array;
+      signatures: Array<Uint8Array>;
+      serializedMessage: Uint8Array;
+    }>([
+      BufferLayout.blob(
+        encodedSignaturesLength.length,
+        'encodedSignaturesLength',
+      ),
+      BufferLayout.seq(
+        Layout.signature(),
+        this.signatures.length,
+        'signatures',
+      ),
+      BufferLayout.blob(serializedMessage.length, 'serializedMessage'),
+    ]);
+
+    const serializedTransaction = new Uint8Array(2048);
+    const serializedTransactionLength = transactionLayout.encode(
+      {
+        encodedSignaturesLength: new Uint8Array(encodedSignaturesLength),
+        signatures: this.signatures,
+        serializedMessage,
+      },
+      serializedTransaction,
+    );
+
+    return serializedTransaction.slice(0, serializedTransactionLength);
+  }
+
+  static deserialize(serializedTransaction: Uint8Array): VersionedTransaction {
+    let byteArray = [...serializedTransaction];
+
+    const signatures = [];
+    const signaturesLength = shortvec.decodeLength(byteArray);
+    for (let i = 0; i < signaturesLength; i++) {
+      signatures.push(
+        new Uint8Array(byteArray.splice(0, SIGNATURE_LENGTH_IN_BYTES)),
+      );
+    }
+
+    const message = VersionedMessage.deserialize(new Uint8Array(byteArray));
+    return new VersionedTransaction(message, signatures);
+  }
+
+  sign(signers: Array<Signer>) {
+    const messageData = this.message.serialize();
+    const signerPubkeys = this.message.staticAccountKeys.slice(
+      0,
+      this.message.header.numRequiredSignatures,
+    );
+    for (const signer of signers) {
+      const signerIndex = signerPubkeys.findIndex(pubkey =>
+        pubkey.equals(signer.publicKey),
+      );
+      assert(
+        signerIndex >= 0,
+        `Cannot sign with non signer key ${signer.publicKey.toBase58()}`,
+      );
+      this.signatures[signerIndex] = sign(messageData, signer.secretKey);
+    }
+  }
+
+  addSignature(publicKey: PublicKey, signature: Uint8Array) {
+    assert(signature.byteLength === 64, 'Signature must be 64 bytes long');
+    const signerPubkeys = this.message.staticAccountKeys.slice(
+      0,
+      this.message.header.numRequiredSignatures,
+    );
+    const signerIndex = signerPubkeys.findIndex(pubkey =>
+      pubkey.equals(publicKey),
+    );
+    assert(
+      signerIndex >= 0,
+      `Can not add signature; \`${publicKey.toBase58()}\` is not required to sign this transaction`,
+    );
+    this.signatures[signerIndex] = signature;
+  }
+}

package/src/utils/bigint.ts

@@ -0,0 +1,43 @@
+import {Buffer} from 'buffer';
+import {blob, Layout} from '@solana/buffer-layout';
+import {toBigIntLE, toBufferLE} from 'bigint-buffer';
+
+interface EncodeDecode<T> {
+  decode(buffer: Buffer, offset?: number): T;
+  encode(src: T, buffer: Buffer, offset?: number): number;
+}
+
+const encodeDecode = <T>(layout: Layout<T>): EncodeDecode<T> => {
+  const decode = layout.decode.bind(layout);
+  const encode = layout.encode.bind(layout);
+  return {decode, encode};
+};
+
+const bigInt =
+  (length: number) =>
+  (property?: string): Layout<bigint> => {
+    const layout = blob(length, property);
+    const {encode, decode} = encodeDecode(layout);
+
+    const bigIntLayout = layout as Layout<unknown> as Layout<bigint>;
+
+    bigIntLayout.decode = (buffer: Buffer, offset: number) => {
+      const src = decode(buffer, offset);
+      return toBigIntLE(Buffer.from(src));
+    };
+
+    bigIntLayout.encode = (bigInt: bigint, buffer: Buffer, offset: number) => {
+      const src = toBufferLE(bigInt, length);
+      return encode(src, buffer, offset);
+    };
+
+    return bigIntLayout;
+  };
+
+export const u64 = bigInt(8);
+
+export const u128 = bigInt(16);
+
+export const u192 = bigInt(24);
+
+export const u256 = bigInt(32);