@solana/web3.js 1.53.0 → 1.54.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@solana/web3.js",
-  "version": "1.53.0",
+  "version": "1.54.0",
   "description": "Solana Javascript API",
   "keywords": [
     "api",
@@ -69,7 +69,6 @@
     "jayson": "^3.4.4",
     "js-sha3": "^0.8.0",
     "node-fetch": "2",
-    "react-native-url-polyfill": "^1.3.0",
     "rpc-websockets": "^7.5.0",
     "secp256k1": "^4.0.2",
     "superstruct": "^0.14.2",

package/src/connection.ts

@@ -43,7 +43,6 @@ import {
   TransactionExpiredTimeoutError,
 } from './transaction/expiry-custom-errors';
 import {makeWebsocketUrl} from './utils/makeWebsocketUrl';
-import {URL} from './utils/url-impl';
 import type {Blockhash} from './blockhash';
 import type {FeeCalculator} from './fee-calculator';
 import type {TransactionSignature} from './transaction';
@@ -305,6 +304,14 @@ export type BlockheightBasedTransactionConfirmationStrategy = {
   signature: TransactionSignature;
 } & BlockhashWithExpiryBlockHeight;
 
+/* @internal */
+function assertEndpointUrl(putativeUrl: string) {
+  if (/^https?:/.test(putativeUrl) === false) {
+    throw new TypeError('Endpoint URL must start with `http:` or `https:`.');
+  }
+  return putativeUrl;
+}
+
 /** @internal */
 function extractCommitmentFromConfig<TConfig>(
   commitmentOrConfig?: Commitment | ({commitment?: Commitment} & TConfig),
@@ -1117,7 +1124,6 @@ export type PerfSample = {
 
 function createRpcClient(
   url: string,
-  useHttps: boolean,
   httpHeaders?: HttpHeaders,
   customFetch?: FetchFn,
   fetchMiddleware?: FetchMiddleware,
@@ -1126,7 +1132,7 @@ function createRpcClient(
   const fetch = customFetch ? customFetch : fetchImpl;
   let agentManager: AgentManager | undefined;
   if (!process.env.BROWSER) {
-    agentManager = new AgentManager(useHttps);
+    agentManager = new AgentManager(url.startsWith('https:') /* useHttps */);
   }
 
   let fetchWithMiddleware: FetchFn | undefined;
@@ -2493,9 +2499,6 @@ export class Connection {
     endpoint: string,
     commitmentOrConfig?: Commitment | ConnectionConfig,
   ) {
-    let url = new URL(endpoint);
-    const useHttps = url.protocol === 'https:';
-
     let wsEndpoint;
     let httpHeaders;
     let fetch;
@@ -2514,12 +2517,11 @@ export class Connection {
       disableRetryOnRateLimit = commitmentOrConfig.disableRetryOnRateLimit;
     }
 
-    this._rpcEndpoint = endpoint;
+    this._rpcEndpoint = assertEndpointUrl(endpoint);
     this._rpcWsEndpoint = wsEndpoint || makeWebsocketUrl(endpoint);
 
     this._rpcClient = createRpcClient(
-      url.toString(),
-      useHttps,
+      endpoint,
       httpHeaders,
       fetch,
       fetchMiddleware,

package/src/layout.ts

@@ -8,6 +8,13 @@ export const publicKey = (property: string = 'publicKey') => {
   return BufferLayout.blob(32, property);
 };
 
+/**
+ * Layout for a signature
+ */
+export const signature = (property: string = 'signature') => {
+  return BufferLayout.blob(64, property);
+};
+
 /**
  * Layout for a 64bit unsigned value
  */

package/src/message/index.ts

@@ -1,4 +1,8 @@
+import {PublicKey} from '../publickey';
+
 export * from './legacy';
+export * from './versioned';
+export * from './v0';
 
 /**
  * The message header, identifying signed and read-only account
@@ -15,18 +19,27 @@ export type MessageHeader = {
   numReadonlyUnsignedAccounts: number;
 };
 
+/**
+ * An address table lookup used to load additional accounts
+ */
+export type MessageAddressTableLookup = {
+  accountKey: PublicKey;
+  writableIndexes: Array<number>;
+  readonlyIndexes: Array<number>;
+};
+
 /**
  * An instruction to execute by a program
  *
  * @property {number} programIdIndex
- * @property {number[]} accounts
- * @property {string} data
+ * @property {number[]} accountKeyIndexes
+ * @property {Uint8Array} data
  */
-export type CompiledInstruction = {
+export type MessageCompiledInstruction = {
   /** Index into the transaction keys array indicating the program account that executes this instruction */
   programIdIndex: number;
   /** Ordered indices into the transaction keys array indicating which accounts to pass to the program */
-  accounts: number[];
-  /** The program input data encoded as base 58 */
-  data: string;
+  accountKeyIndexes: number[];
+  /** The program input data */
+  data: Uint8Array;
 };

package/src/message/legacy.ts

@@ -2,13 +2,33 @@ import bs58 from 'bs58';
 import {Buffer} from 'buffer';
 import * as BufferLayout from '@solana/buffer-layout';
 
-import {PublicKey} from '../publickey';
+import {PublicKey, PUBLIC_KEY_LENGTH} from '../publickey';
 import type {Blockhash} from '../blockhash';
 import * as Layout from '../layout';
-import {PACKET_DATA_SIZE} from '../transaction/constants';
+import {PACKET_DATA_SIZE, VERSION_PREFIX_MASK} from '../transaction/constants';
 import * as shortvec from '../utils/shortvec-encoding';
 import {toBuffer} from '../utils/to-buffer';
-import {CompiledInstruction, MessageHeader} from './index';
+import {
+  MessageHeader,
+  MessageAddressTableLookup,
+  MessageCompiledInstruction,
+} from './index';
+
+/**
+ * An instruction to execute by a program
+ *
+ * @property {number} programIdIndex
+ * @property {number[]} accounts
+ * @property {string} data
+ */
+export type CompiledInstruction = {
+  /** Index into the transaction keys array indicating the program account that executes this instruction */
+  programIdIndex: number;
+  /** Ordered indices into the transaction keys array indicating which accounts to pass to the program */
+  accounts: number[];
+  /** The program input data encoded as base 58 */
+  data: string;
+};
 
 /**
  * Message constructor arguments
@@ -24,8 +44,6 @@ export type MessageArgs = {
   instructions: CompiledInstruction[];
 };
 
-const PUBKEY_LENGTH = 32;
-
 /**
  * List of instructions to be processed atomically
  */
@@ -53,6 +71,28 @@ export class Message {
     );
   }
 
+  get version(): 'legacy' {
+    return 'legacy';
+  }
+
+  get staticAccountKeys(): Array<PublicKey> {
+    return this.accountKeys;
+  }
+
+  get compiledInstructions(): Array<MessageCompiledInstruction> {
+    return this.instructions.map(
+      (ix): MessageCompiledInstruction => ({
+        programIdIndex: ix.programIdIndex,
+        accountKeyIndexes: ix.accounts,
+        data: bs58.decode(ix.data),
+      }),
+    );
+  }
+
+  get addressTableLookups(): Array<MessageAddressTableLookup> {
+    return [];
+  }
+
   isAccountSigner(index: number): boolean {
     return index < this.header.numRequiredSignatures;
   }
@@ -193,19 +233,28 @@ export class Message {
     let byteArray = [...buffer];
 
     const numRequiredSignatures = byteArray.shift() as number;
+    if (
+      numRequiredSignatures !==
+      (numRequiredSignatures & VERSION_PREFIX_MASK)
+    ) {
+      throw new Error(
+        'Versioned messages must be deserialized with VersionedMessage.deserialize()',
+      );
+    }
+
     const numReadonlySignedAccounts = byteArray.shift() as number;
     const numReadonlyUnsignedAccounts = byteArray.shift() as number;
 
     const accountCount = shortvec.decodeLength(byteArray);
     let accountKeys = [];
     for (let i = 0; i < accountCount; i++) {
-      const account = byteArray.slice(0, PUBKEY_LENGTH);
-      byteArray = byteArray.slice(PUBKEY_LENGTH);
+      const account = byteArray.slice(0, PUBLIC_KEY_LENGTH);
+      byteArray = byteArray.slice(PUBLIC_KEY_LENGTH);
       accountKeys.push(bs58.encode(Buffer.from(account)));
     }
 
-    const recentBlockhash = byteArray.slice(0, PUBKEY_LENGTH);
-    byteArray = byteArray.slice(PUBKEY_LENGTH);
+    const recentBlockhash = byteArray.slice(0, PUBLIC_KEY_LENGTH);
+    byteArray = byteArray.slice(PUBLIC_KEY_LENGTH);
 
     const instructionCount = shortvec.decodeLength(byteArray);
     let instructions: CompiledInstruction[] = [];

package/src/message/v0.ts

@@ -0,0 +1,324 @@
+import bs58 from 'bs58';
+import * as BufferLayout from '@solana/buffer-layout';
+
+import * as Layout from '../layout';
+import {Blockhash} from '../blockhash';
+import {
+  MessageHeader,
+  MessageAddressTableLookup,
+  MessageCompiledInstruction,
+} from './index';
+import {PublicKey, PUBLIC_KEY_LENGTH} from '../publickey';
+import * as shortvec from '../utils/shortvec-encoding';
+import assert from '../utils/assert';
+import {PACKET_DATA_SIZE, VERSION_PREFIX_MASK} from '../transaction/constants';
+
+/**
+ * Message constructor arguments
+ */
+export type MessageV0Args = {
+  /** The message header, identifying signed and read-only `accountKeys` */
+  header: MessageHeader;
+  /** The static account keys used by this transaction */
+  staticAccountKeys: PublicKey[];
+  /** The hash of a recent ledger block */
+  recentBlockhash: Blockhash;
+  /** Instructions that will be executed in sequence and committed in one atomic transaction if all succeed. */
+  compiledInstructions: MessageCompiledInstruction[];
+  /** Instructions that will be executed in sequence and committed in one atomic transaction if all succeed. */
+  addressTableLookups: MessageAddressTableLookup[];
+};
+
+export class MessageV0 {
+  header: MessageHeader;
+  staticAccountKeys: Array<PublicKey>;
+  recentBlockhash: Blockhash;
+  compiledInstructions: Array<MessageCompiledInstruction>;
+  addressTableLookups: Array<MessageAddressTableLookup>;
+
+  constructor(args: MessageV0Args) {
+    this.header = args.header;
+    this.staticAccountKeys = args.staticAccountKeys;
+    this.recentBlockhash = args.recentBlockhash;
+    this.compiledInstructions = args.compiledInstructions;
+    this.addressTableLookups = args.addressTableLookups;
+  }
+
+  get version(): 0 {
+    return 0;
+  }
+
+  serialize(): Uint8Array {
+    const encodedStaticAccountKeysLength = Array<number>();
+    shortvec.encodeLength(
+      encodedStaticAccountKeysLength,
+      this.staticAccountKeys.length,
+    );
+
+    const serializedInstructions = this.serializeInstructions();
+    const encodedInstructionsLength = Array<number>();
+    shortvec.encodeLength(
+      encodedInstructionsLength,
+      this.compiledInstructions.length,
+    );
+
+    const serializedAddressTableLookups = this.serializeAddressTableLookups();
+    const encodedAddressTableLookupsLength = Array<number>();
+    shortvec.encodeLength(
+      encodedAddressTableLookupsLength,
+      this.addressTableLookups.length,
+    );
+
+    const messageLayout = BufferLayout.struct<{
+      prefix: number;
+      header: MessageHeader;
+      staticAccountKeysLength: Uint8Array;
+      staticAccountKeys: Array<Uint8Array>;
+      recentBlockhash: Uint8Array;
+      instructionsLength: Uint8Array;
+      serializedInstructions: Uint8Array;
+      addressTableLookupsLength: Uint8Array;
+      serializedAddressTableLookups: Uint8Array;
+    }>([
+      BufferLayout.u8('prefix'),
+      BufferLayout.struct<MessageHeader>(
+        [
+          BufferLayout.u8('numRequiredSignatures'),
+          BufferLayout.u8('numReadonlySignedAccounts'),
+          BufferLayout.u8('numReadonlyUnsignedAccounts'),
+        ],
+        'header',
+      ),
+      BufferLayout.blob(
+        encodedStaticAccountKeysLength.length,
+        'staticAccountKeysLength',
+      ),
+      BufferLayout.seq(
+        Layout.publicKey(),
+        this.staticAccountKeys.length,
+        'staticAccountKeys',
+      ),
+      Layout.publicKey('recentBlockhash'),
+      BufferLayout.blob(encodedInstructionsLength.length, 'instructionsLength'),
+      BufferLayout.blob(
+        serializedInstructions.length,
+        'serializedInstructions',
+      ),
+      BufferLayout.blob(
+        encodedAddressTableLookupsLength.length,
+        'addressTableLookupsLength',
+      ),
+      BufferLayout.blob(
+        serializedAddressTableLookups.length,
+        'serializedAddressTableLookups',
+      ),
+    ]);
+
+    const serializedMessage = new Uint8Array(PACKET_DATA_SIZE);
+    const MESSAGE_VERSION_0_PREFIX = 1 << 7;
+    const serializedMessageLength = messageLayout.encode(
+      {
+        prefix: MESSAGE_VERSION_0_PREFIX,
+        header: this.header,
+        staticAccountKeysLength: new Uint8Array(encodedStaticAccountKeysLength),
+        staticAccountKeys: this.staticAccountKeys.map(key => key.toBytes()),
+        recentBlockhash: bs58.decode(this.recentBlockhash),
+        instructionsLength: new Uint8Array(encodedInstructionsLength),
+        serializedInstructions,
+        addressTableLookupsLength: new Uint8Array(
+          encodedAddressTableLookupsLength,
+        ),
+        serializedAddressTableLookups,
+      },
+      serializedMessage,
+    );
+    return serializedMessage.slice(0, serializedMessageLength);
+  }
+
+  private serializeInstructions(): Uint8Array {
+    let serializedLength = 0;
+    const serializedInstructions = new Uint8Array(PACKET_DATA_SIZE);
+    for (const instruction of this.compiledInstructions) {
+      const encodedAccountKeyIndexesLength = Array<number>();
+      shortvec.encodeLength(
+        encodedAccountKeyIndexesLength,
+        instruction.accountKeyIndexes.length,
+      );
+
+      const encodedDataLength = Array<number>();
+      shortvec.encodeLength(encodedDataLength, instruction.data.length);
+
+      const instructionLayout = BufferLayout.struct<{
+        programIdIndex: number;
+        encodedAccountKeyIndexesLength: Uint8Array;
+        accountKeyIndexes: number[];
+        encodedDataLength: Uint8Array;
+        data: Uint8Array;
+      }>([
+        BufferLayout.u8('programIdIndex'),
+        BufferLayout.blob(
+          encodedAccountKeyIndexesLength.length,
+          'encodedAccountKeyIndexesLength',
+        ),
+        BufferLayout.seq(
+          BufferLayout.u8(),
+          instruction.accountKeyIndexes.length,
+          'accountKeyIndexes',
+        ),
+        BufferLayout.blob(encodedDataLength.length, 'encodedDataLength'),
+        BufferLayout.blob(instruction.data.length, 'data'),
+      ]);
+
+      serializedLength += instructionLayout.encode(
+        {
+          programIdIndex: instruction.programIdIndex,
+          encodedAccountKeyIndexesLength: new Uint8Array(
+            encodedAccountKeyIndexesLength,
+          ),
+          accountKeyIndexes: instruction.accountKeyIndexes,
+          encodedDataLength: new Uint8Array(encodedDataLength),
+          data: instruction.data,
+        },
+        serializedInstructions,
+        serializedLength,
+      );
+    }
+
+    return serializedInstructions.slice(0, serializedLength);
+  }
+
+  private serializeAddressTableLookups(): Uint8Array {
+    let serializedLength = 0;
+    const serializedAddressTableLookups = new Uint8Array(PACKET_DATA_SIZE);
+    for (const lookup of this.addressTableLookups) {
+      const encodedWritableIndexesLength = Array<number>();
+      shortvec.encodeLength(
+        encodedWritableIndexesLength,
+        lookup.writableIndexes.length,
+      );
+
+      const encodedReadonlyIndexesLength = Array<number>();
+      shortvec.encodeLength(
+        encodedReadonlyIndexesLength,
+        lookup.readonlyIndexes.length,
+      );
+
+      const addressTableLookupLayout = BufferLayout.struct<{
+        accountKey: Uint8Array;
+        encodedWritableIndexesLength: Uint8Array;
+        writableIndexes: number[];
+        encodedReadonlyIndexesLength: Uint8Array;
+        readonlyIndexes: number[];
+      }>([
+        Layout.publicKey('accountKey'),
+        BufferLayout.blob(
+          encodedWritableIndexesLength.length,
+          'encodedWritableIndexesLength',
+        ),
+        BufferLayout.seq(
+          BufferLayout.u8(),
+          lookup.writableIndexes.length,
+          'writableIndexes',
+        ),
+        BufferLayout.blob(
+          encodedReadonlyIndexesLength.length,
+          'encodedReadonlyIndexesLength',
+        ),
+        BufferLayout.seq(
+          BufferLayout.u8(),
+          lookup.readonlyIndexes.length,
+          'readonlyIndexes',
+        ),
+      ]);
+
+      serializedLength += addressTableLookupLayout.encode(
+        {
+          accountKey: lookup.accountKey.toBytes(),
+          encodedWritableIndexesLength: new Uint8Array(
+            encodedWritableIndexesLength,
+          ),
+          writableIndexes: lookup.writableIndexes,
+          encodedReadonlyIndexesLength: new Uint8Array(
+            encodedReadonlyIndexesLength,
+          ),
+          readonlyIndexes: lookup.readonlyIndexes,
+        },
+        serializedAddressTableLookups,
+        serializedLength,
+      );
+    }
+
+    return serializedAddressTableLookups.slice(0, serializedLength);
+  }
+
+  static deserialize(serializedMessage: Uint8Array): MessageV0 {
+    let byteArray = [...serializedMessage];
+
+    const prefix = byteArray.shift() as number;
+    const maskedPrefix = prefix & VERSION_PREFIX_MASK;
+    assert(
+      prefix !== maskedPrefix,
+      `Expected versioned message but received legacy message`,
+    );
+
+    const version = maskedPrefix;
+    assert(
+      version === 0,
+      `Expected versioned message with version 0 but found version ${version}`,
+    );
+
+    const header: MessageHeader = {
+      numRequiredSignatures: byteArray.shift() as number,
+      numReadonlySignedAccounts: byteArray.shift() as number,
+      numReadonlyUnsignedAccounts: byteArray.shift() as number,
+    };
+
+    const staticAccountKeys = [];
+    const staticAccountKeysLength = shortvec.decodeLength(byteArray);
+    for (let i = 0; i < staticAccountKeysLength; i++) {
+      staticAccountKeys.push(
+        new PublicKey(byteArray.splice(0, PUBLIC_KEY_LENGTH)),
+      );
+    }
+
+    const recentBlockhash = bs58.encode(byteArray.splice(0, PUBLIC_KEY_LENGTH));
+
+    const instructionCount = shortvec.decodeLength(byteArray);
+    const compiledInstructions: MessageCompiledInstruction[] = [];
+    for (let i = 0; i < instructionCount; i++) {
+      const programIdIndex = byteArray.shift() as number;
+      const accountKeyIndexesLength = shortvec.decodeLength(byteArray);
+      const accountKeyIndexes = byteArray.splice(0, accountKeyIndexesLength);
+      const dataLength = shortvec.decodeLength(byteArray);
+      const data = new Uint8Array(byteArray.splice(0, dataLength));
+      compiledInstructions.push({
+        programIdIndex,
+        accountKeyIndexes,
+        data,
+      });
+    }
+
+    const addressTableLookupsCount = shortvec.decodeLength(byteArray);
+    const addressTableLookups: MessageAddressTableLookup[] = [];
+    for (let i = 0; i < addressTableLookupsCount; i++) {
+      const accountKey = new PublicKey(byteArray.splice(0, PUBLIC_KEY_LENGTH));
+      const writableIndexesLength = shortvec.decodeLength(byteArray);
+      const writableIndexes = byteArray.splice(0, writableIndexesLength);
+      const readonlyIndexesLength = shortvec.decodeLength(byteArray);
+      const readonlyIndexes = byteArray.splice(0, readonlyIndexesLength);
+      addressTableLookups.push({
+        accountKey,
+        writableIndexes,
+        readonlyIndexes,
+      });
+    }
+
+    return new MessageV0({
+      header,
+      staticAccountKeys,
+      recentBlockhash,
+      compiledInstructions,
+      addressTableLookups,
+    });
+  }
+}

package/src/message/versioned.ts

@@ -0,0 +1,27 @@
+import {VERSION_PREFIX_MASK} from '../transaction/constants';
+import {Message} from './legacy';
+import {MessageV0} from './v0';
+
+export type VersionedMessage = Message | MessageV0;
+// eslint-disable-next-line no-redeclare
+export const VersionedMessage = {
+  deserialize: (serializedMessage: Uint8Array): VersionedMessage => {
+    const prefix = serializedMessage[0];
+    const maskedPrefix = prefix & VERSION_PREFIX_MASK;
+
+    // if the highest bit of the prefix is not set, the message is not versioned
+    if (maskedPrefix === prefix) {
+      return Message.from(serializedMessage);
+    }
+
+    // the lower 7 bits of the prefix indicate the message version
+    const version = maskedPrefix;
+    if (version === 0) {
+      return MessageV0.deserialize(serializedMessage);
+    } else {
+      throw new Error(
+        `Transaction message version ${version} deserialization is not supported`,
+      );
+    }
+  },
+};

package/src/programs/vote.ts

@@ -410,4 +410,25 @@ export class VoteProgram {
       data,
     });
   }
+
+  /**
+   * Generate a transaction to withdraw safely from a Vote account.
+   *
+   * This function was created as a safeguard for vote accounts running validators, `safeWithdraw`
+   * checks that the withdraw amount will not exceed the specified balance while leaving enough left
+   * to cover rent. If you wish to close the vote account by withdrawing the full amount, call the
+   * `withdraw` method directly.
+   */
+  static safeWithdraw(
+    params: WithdrawFromVoteAccountParams,
+    currentVoteAccountBalance: number,
+    rentExemptMinimum: number,
+  ): Transaction {
+    if (params.lamports > currentVoteAccountBalance - rentExemptMinimum) {
+      throw new Error(
+        'Withdraw will leave vote account with insuffcient funds.',
+      );
+    }
+    return VoteProgram.withdraw(params);
+  }
 }

package/src/publickey.ts

@@ -12,6 +12,11 @@ import {toBuffer} from './utils/to-buffer';
  */
 export const MAX_SEED_LENGTH = 32;
 
+/**
+ * Size of public key in bytes
+ */
+export const PUBLIC_KEY_LENGTH = 32;
+
 /**
  * Value to be converted into public key
  */
@@ -54,7 +59,7 @@ export class PublicKey extends Struct {
       if (typeof value === 'string') {
         // assume base 58 encoding by default
         const decoded = bs58.decode(value);
-        if (decoded.length != 32) {
+        if (decoded.length != PUBLIC_KEY_LENGTH) {
           throw new Error(`Invalid public key input`);
         }
         this._bn = new BN(decoded);
@@ -103,7 +108,7 @@ export class PublicKey extends Struct {
    */
   toBuffer(): Buffer {
     const b = this._bn.toArrayLike(Buffer);
-    if (b.length === 32) {
+    if (b.length === PUBLIC_KEY_LENGTH) {
       return b;
     }
 

package/src/transaction/constants.ts

@@ -7,4 +7,6 @@
  */
 export const PACKET_DATA_SIZE = 1280 - 40 - 8;
 
+export const VERSION_PREFIX_MASK = 0x7f;
+
 export const SIGNATURE_LENGTH_IN_BYTES = 64;

package/src/transaction/index.ts

@@ -1,3 +1,4 @@
 export * from './constants';
 export * from './expiry-custom-errors';
 export * from './legacy';
+export * from './versioned';