starknet 2.8.0 → 2.9.0

package/CHANGELOG.md

@@ -1,3 +1,13 @@
+# [2.9.0](https://github.com/seanjameshan/starknet.js/compare/v2.8.0...v2.9.0) (2022-02-04)
+
+### Bug Fixes
+
+- introduce block identifier type ([75599a9](https://github.com/seanjameshan/starknet.js/commit/75599a99bbcb5723cfc8575b5fbf994a0bbf5b67))
+
+### Features
+
+- **utils:** add validateAndParseAddress function ([c067fc4](https://github.com/seanjameshan/starknet.js/commit/c067fc443e4dc9c22b78ed6c093978a2f37debde))
+
 # [2.8.0](https://github.com/seanjameshan/starknet.js/compare/v2.7.2...v2.8.0) (2022-02-02)
 
 ### Features

package/__tests__/provider.test.ts

@@ -21,7 +21,7 @@ describe('defaultProvider', () => {
       ).resolves.not.toThrow();
     });
     test('getBlock(blockHash=undefined, blockNumber=36657)', () => {
-      return expect(defaultProvider.getBlock(undefined, 36657)).resolves.not.toThrow();
+      return expect(defaultProvider.getBlock(36657)).resolves.not.toThrow();
     });
     test('getBlock(blockHash=undefined, blockNumber=null)', () => {
       return expect(defaultProvider.getBlock()).resolves.not.toThrow();
@@ -34,7 +34,6 @@ describe('defaultProvider', () => {
       return expect(
         defaultProvider.getCode(
           '0x01d1f307c073bb786a66e6e042ec2a9bdc385a3373bb3738d95b966d5ce56166',
-          undefined,
           36663
         )
       ).resolves.not.toThrow();
@@ -51,7 +50,6 @@ describe('defaultProvider', () => {
         defaultProvider.getStorageAt(
           '0x01d1f307c073bb786a66e6e042ec2a9bdc385a3373bb3738d95b966d5ce56166',
           0,
-          undefined,
           36663
         )
       ).resolves.not.toThrow();

package/__tests__/utils/address.test.ts

@@ -0,0 +1,16 @@
+import { addAddressPadding, validateAndParseAddress } from '../../src/utils/address';
+// import { addHexPrefix, removeHexPrefix } from '../../src/utils/encode';
+
+describe('validateAndParseAddress', () => {
+  test('should pass when correct starknet address is passed', () => {
+    const addr = '0x7ee790591d9fa3efc87067d95a643f8455e0b8190eb8cb7bfd39e4fb7571fdf';
+
+    return expect(validateAndParseAddress(addr)).toEqual(`${addAddressPadding(addr)}`);
+  });
+
+  test('should add 0x prefix if not provided', () => {
+    const addr = '0x6eff1d71068df8e6677f59a556151c56ed13e14ad431a9bef6fcb3fc5e6fa7';
+
+    return expect(validateAndParseAddress(addr)).toEqual(`${addAddressPadding(addr)}`);
+  });
+});

package/constants.d.ts

@@ -4,6 +4,7 @@ export declare const ZERO: import('bn.js');
 export declare const ONE: import('bn.js');
 export declare const TWO: import('bn.js');
 export declare const MASK_250: import('bn.js');
+export declare const MASK_251: import('bn.js');
 /**
  * The following is taken from https://github.com/starkware-libs/starkex-resources/blob/master/crypto/starkware/crypto/signature/pedersen_params.json but converted to hex, because JS is very bad handling big integers by default
  * Please do not edit until the JSON changes.
@@ -11,6 +12,7 @@ export declare const MASK_250: import('bn.js');
 export declare const FIELD_PRIME =
   '800000000000011000000000000000000000000000000000000000000000001';
 export declare const FIELD_GEN = '3';
+export declare const FIELD_SIZE = 251;
 export declare const EC_ORDER = '800000000000010FFFFFFFFFFFFFFFFB781126DCAE7B2321E66A241ADC64D2F';
 export declare const ALPHA = '1';
 export declare const BETA = '6F21413EFBE40DE150E596D72F7A8C5609AD26C15C915C1F4CDFCB99CEE9E89';

package/constants.js

@@ -5,8 +5,10 @@ exports.CONSTANT_POINTS =
   exports.BETA =
   exports.ALPHA =
   exports.EC_ORDER =
+  exports.FIELD_SIZE =
   exports.FIELD_GEN =
   exports.FIELD_PRIME =
+  exports.MASK_251 =
   exports.MASK_250 =
   exports.TWO =
   exports.ONE =
@@ -25,12 +27,14 @@ exports.ZERO = (0, number_1.toBN)(0);
 exports.ONE = (0, number_1.toBN)(1);
 exports.TWO = (0, number_1.toBN)(2);
 exports.MASK_250 = exports.TWO.pow((0, number_1.toBN)(250)).sub(exports.ONE); // 2 ** 250 - 1
+exports.MASK_251 = exports.TWO.pow((0, number_1.toBN)(251));
 /**
  * The following is taken from https://github.com/starkware-libs/starkex-resources/blob/master/crypto/starkware/crypto/signature/pedersen_params.json but converted to hex, because JS is very bad handling big integers by default
  * Please do not edit until the JSON changes.
  */
 exports.FIELD_PRIME = '800000000000011000000000000000000000000000000000000000000000001';
 exports.FIELD_GEN = '3';
+exports.FIELD_SIZE = 251;
 exports.EC_ORDER = '800000000000010FFFFFFFFFFFFFFFFB781126DCAE7B2321E66A241ADC64D2F';
 exports.ALPHA = '1';
 exports.BETA = '6F21413EFBE40DE150E596D72F7A8C5609AD26C15C915C1F4CDFCB99CEE9E89';

package/dist/constants.d.ts

@@ -4,12 +4,14 @@ export declare const ZERO: import("bn.js");
 export declare const ONE: import("bn.js");
 export declare const TWO: import("bn.js");
 export declare const MASK_250: import("bn.js");
+export declare const MASK_251: import("bn.js");
 /**
  * The following is taken from https://github.com/starkware-libs/starkex-resources/blob/master/crypto/starkware/crypto/signature/pedersen_params.json but converted to hex, because JS is very bad handling big integers by default
  * Please do not edit until the JSON changes.
  */
 export declare const FIELD_PRIME = "800000000000011000000000000000000000000000000000000000000000001";
 export declare const FIELD_GEN = "3";
+export declare const FIELD_SIZE = 251;
 export declare const EC_ORDER = "800000000000010FFFFFFFFFFFFFFFFB781126DCAE7B2321E66A241ADC64D2F";
 export declare const ALPHA = "1";
 export declare const BETA = "6F21413EFBE40DE150E596D72F7A8C5609AD26C15C915C1F4CDFCB99CEE9E89";

package/dist/constants.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.CONSTANT_POINTS = exports.MAX_ECDSA_VAL = exports.BETA = exports.ALPHA = exports.EC_ORDER = exports.FIELD_GEN = exports.FIELD_PRIME = exports.MASK_250 = exports.TWO = exports.ONE = exports.ZERO = exports.IS_BROWSER = void 0;
+exports.CONSTANT_POINTS = exports.MAX_ECDSA_VAL = exports.BETA = exports.ALPHA = exports.EC_ORDER = exports.FIELD_SIZE = exports.FIELD_GEN = exports.FIELD_PRIME = exports.MASK_251 = exports.MASK_250 = exports.TWO = exports.ONE = exports.ZERO = exports.IS_BROWSER = void 0;
 var number_1 = require("./utils/number");
 var encode_1 = require("./utils/encode");
 Object.defineProperty(exports, "IS_BROWSER", { enumerable: true, get: function () { return encode_1.IS_BROWSER; } });
@@ -8,12 +8,14 @@ exports.ZERO = (0, number_1.toBN)(0);
 exports.ONE = (0, number_1.toBN)(1);
 exports.TWO = (0, number_1.toBN)(2);
 exports.MASK_250 = exports.TWO.pow((0, number_1.toBN)(250)).sub(exports.ONE); // 2 ** 250 - 1
+exports.MASK_251 = exports.TWO.pow((0, number_1.toBN)(251));
 /**
  * The following is taken from https://github.com/starkware-libs/starkex-resources/blob/master/crypto/starkware/crypto/signature/pedersen_params.json but converted to hex, because JS is very bad handling big integers by default
  * Please do not edit until the JSON changes.
  */
 exports.FIELD_PRIME = '800000000000011000000000000000000000000000000000000000000000001';
 exports.FIELD_GEN = '3';
+exports.FIELD_SIZE = 251;
 exports.EC_ORDER = '800000000000010FFFFFFFFFFFFFFFFB781126DCAE7B2321E66A241ADC64D2F';
 exports.ALPHA = '1';
 exports.BETA = '6F21413EFBE40DE150E596D72F7A8C5609AD26C15C915C1F4CDFCB99CEE9E89';

package/dist/index.d.ts

@@ -18,3 +18,4 @@ export * as ec from './utils/ellipticCurve';
 export * as uint256 from './utils/uint256';
 export * as shortString from './utils/shortString';
 export * as typedData from './utils/typedData';
+export * from './utils/address';

package/dist/index.js

@@ -43,3 +43,4 @@ exports.ec = __importStar(require("./utils/ellipticCurve"));
 exports.uint256 = __importStar(require("./utils/uint256"));
 exports.shortString = __importStar(require("./utils/shortString"));
 exports.typedData = __importStar(require("./utils/typedData"));
+__exportStar(require("./utils/address"), exports);

package/dist/provider/default.d.ts

@@ -1,6 +1,7 @@
-import { AddTransactionResponse, BlockNumber, CallContractResponse, CallContractTransaction, CompiledContract, GetBlockResponse, GetCodeResponse, GetContractAddressesResponse, GetTransactionResponse, GetTransactionStatusResponse, Signature, Transaction } from '../types';
+import { AddTransactionResponse, CallContractResponse, CallContractTransaction, CompiledContract, GetBlockResponse, GetCodeResponse, GetContractAddressesResponse, GetTransactionResponse, GetTransactionStatusResponse, Signature, Transaction } from '../types';
 import { BigNumberish } from '../utils/number';
 import { ProviderInterface } from './interface';
+import { BlockIdentifier } from './utils';
 declare type NetworkName = 'mainnet-alpha' | 'goerli-alpha';
 declare type ProviderOptions = {
     network: NetworkName;
@@ -30,7 +31,7 @@ export declare class Provider implements ProviderInterface {
      * @param blockNumber
      * @returns the result of the function on the smart contract.
      */
-    callContract(invokeTransaction: CallContractTransaction, blockHash?: BigNumberish, blockNumber?: BlockNumber): Promise<CallContractResponse>;
+    callContract(invokeTransaction: CallContractTransaction, blockIdentifier?: BlockIdentifier): Promise<CallContractResponse>;
     /**
      * Gets the block information
      *
@@ -40,7 +41,7 @@ export declare class Provider implements ProviderInterface {
      * @param blockNumber
      * @returns the block object { block_number, previous_block_number, state_root, status, timestamp, transaction_receipts, transactions }
      */
-    getBlock(blockHash?: BigNumberish, blockNumber?: BlockNumber): Promise<GetBlockResponse>;
+    getBlock(blockIdentifier?: BlockIdentifier): Promise<GetBlockResponse>;
     /**
      * Gets the code of the deployed contract.
      *
@@ -51,7 +52,7 @@ export declare class Provider implements ProviderInterface {
      * @param blockNumber
      * @returns Bytecode and ABI of compiled contract
      */
-    getCode(contractAddress: string, blockHash?: BigNumberish, blockNumber?: BlockNumber): Promise<GetCodeResponse>;
+    getCode(contractAddress: string, blockIdentifier?: BlockIdentifier): Promise<GetCodeResponse>;
     /**
      * Gets the contract's storage variable at a specific key.
      *
@@ -63,7 +64,7 @@ export declare class Provider implements ProviderInterface {
      * @param blockNumber
      * @returns the value of the storage variable
      */
-    getStorageAt(contractAddress: string, key: number, blockHash?: BigNumberish, blockNumber?: BlockNumber): Promise<object>;
+    getStorageAt(contractAddress: string, key: number, blockIdentifier?: BlockIdentifier): Promise<object>;
     /**
      * Gets the status of a transaction.
      *

package/dist/provider/default.js

@@ -115,14 +115,14 @@ var Provider = /** @class */ (function () {
      * @param blockNumber
      * @returns the result of the function on the smart contract.
      */
-    Provider.prototype.callContract = function (invokeTransaction, blockHash, blockNumber) {
-        if (blockNumber === void 0) { blockNumber = null; }
+    Provider.prototype.callContract = function (invokeTransaction, blockIdentifier) {
+        if (blockIdentifier === void 0) { blockIdentifier = null; }
         return __awaiter(this, void 0, void 0, function () {
             var formattedBlockIdentifier, data;
             return __generator(this, function (_a) {
                 switch (_a.label) {
                     case 0:
-                        formattedBlockIdentifier = (0, utils_1.getFormattedBlockIdentifier)(blockHash, blockNumber);
+                        formattedBlockIdentifier = (0, utils_1.getFormattedBlockIdentifier)(blockIdentifier);
                         return [4 /*yield*/, axios_1.default.post((0, url_join_1.default)(this.feederGatewayUrl, 'call_contract', formattedBlockIdentifier), __assign({ signature: [], calldata: [] }, invokeTransaction))];
                     case 1:
                         data = (_a.sent()).data;
@@ -140,14 +140,14 @@ var Provider = /** @class */ (function () {
      * @param blockNumber
      * @returns the block object { block_number, previous_block_number, state_root, status, timestamp, transaction_receipts, transactions }
      */
-    Provider.prototype.getBlock = function (blockHash, blockNumber) {
-        if (blockNumber === void 0) { blockNumber = null; }
+    Provider.prototype.getBlock = function (blockIdentifier) {
+        if (blockIdentifier === void 0) { blockIdentifier = null; }
         return __awaiter(this, void 0, void 0, function () {
             var formattedBlockIdentifier, data;
             return __generator(this, function (_a) {
                 switch (_a.label) {
                     case 0:
-                        formattedBlockIdentifier = (0, utils_1.getFormattedBlockIdentifier)(blockHash, blockNumber);
+                        formattedBlockIdentifier = (0, utils_1.getFormattedBlockIdentifier)(blockIdentifier);
                         return [4 /*yield*/, axios_1.default.get((0, url_join_1.default)(this.feederGatewayUrl, 'get_block', formattedBlockIdentifier))];
                     case 1:
                         data = (_a.sent()).data;
@@ -166,14 +166,14 @@ var Provider = /** @class */ (function () {
      * @param blockNumber
      * @returns Bytecode and ABI of compiled contract
      */
-    Provider.prototype.getCode = function (contractAddress, blockHash, blockNumber) {
-        if (blockNumber === void 0) { blockNumber = null; }
+    Provider.prototype.getCode = function (contractAddress, blockIdentifier) {
+        if (blockIdentifier === void 0) { blockIdentifier = null; }
         return __awaiter(this, void 0, void 0, function () {
             var formattedBlockIdentifier, data;
             return __generator(this, function (_a) {
                 switch (_a.label) {
                     case 0:
-                        formattedBlockIdentifier = (0, utils_1.getFormattedBlockIdentifier)(blockHash, blockNumber);
+                        formattedBlockIdentifier = (0, utils_1.getFormattedBlockIdentifier)(blockIdentifier);
                         return [4 /*yield*/, axios_1.default.get((0, url_join_1.default)(this.feederGatewayUrl, 'get_code', "?contractAddress=" + contractAddress + "&" + formattedBlockIdentifier))];
                     case 1:
                         data = (_a.sent()).data;
@@ -194,14 +194,14 @@ var Provider = /** @class */ (function () {
      * @param blockNumber
      * @returns the value of the storage variable
      */
-    Provider.prototype.getStorageAt = function (contractAddress, key, blockHash, blockNumber) {
-        if (blockNumber === void 0) { blockNumber = null; }
+    Provider.prototype.getStorageAt = function (contractAddress, key, blockIdentifier) {
+        if (blockIdentifier === void 0) { blockIdentifier = null; }
         return __awaiter(this, void 0, void 0, function () {
             var formattedBlockIdentifier, data;
             return __generator(this, function (_a) {
                 switch (_a.label) {
                     case 0:
-                        formattedBlockIdentifier = (0, utils_1.getFormattedBlockIdentifier)(blockHash, blockNumber);
+                        formattedBlockIdentifier = (0, utils_1.getFormattedBlockIdentifier)(blockIdentifier);
                         return [4 /*yield*/, axios_1.default.get((0, url_join_1.default)(this.feederGatewayUrl, 'get_storage_at', "?contractAddress=" + contractAddress + "&key=" + key + "&" + formattedBlockIdentifier))];
                     case 1:
                         data = (_a.sent()).data;

package/dist/provider/interface.d.ts

@@ -1,5 +1,6 @@
-import type { AddTransactionResponse, BlockNumber, CallContractResponse, CallContractTransaction, CompiledContract, GetBlockResponse, GetCodeResponse, GetContractAddressesResponse, GetTransactionResponse, GetTransactionStatusResponse, Signature, Transaction } from '../types';
+import type { AddTransactionResponse, CallContractResponse, CallContractTransaction, CompiledContract, GetBlockResponse, GetCodeResponse, GetContractAddressesResponse, GetTransactionResponse, GetTransactionStatusResponse, Signature, Transaction } from '../types';
 import type { BigNumberish } from '../utils/number';
+import { BlockIdentifier } from './utils';
 export declare abstract class ProviderInterface {
     abstract baseUrl: string;
     abstract feederGatewayUrl: string;
@@ -17,32 +18,29 @@ export declare abstract class ProviderInterface {
      * [Reference](https://github.com/starkware-libs/cairo-lang/blob/fc97bdd8322a7df043c87c371634b26c15ed6cee/src/starkware/starknet/services/api/feeder_gateway/feeder_gateway_client.py#L25-L39)
      *
      * @param invokeTransaction - transaction to be invoked
-     * @param blockHash
-     * @param blockNumber
+     * @param blockIdentifier - block identifier
      * @returns the result of the function on the smart contract.
      */
-    abstract callContract(invokeTransaction: CallContractTransaction, blockHash?: BigNumberish, blockNumber?: BlockNumber): Promise<CallContractResponse>;
+    abstract callContract(invokeTransaction: CallContractTransaction, blockIdentifier?: BlockIdentifier): Promise<CallContractResponse>;
     /**
      * Gets the block information
      *
      * [Reference](https://github.com/starkware-libs/cairo-lang/blob/fc97bdd8322a7df043c87c371634b26c15ed6cee/src/starkware/starknet/services/api/feeder_gateway/feeder_gateway_client.py#L41-L53)
      *
-     * @param blockHash
-     * @param blockNumber
+     * @param blockIdentifier - block identifier
      * @returns the block object { block_number, previous_block_number, state_root, status, timestamp, transaction_receipts, transactions }
      */
-    abstract getBlock(blockHash?: BigNumberish, blockNumber?: BlockNumber): Promise<GetBlockResponse>;
+    abstract getBlock(blockIdentifier?: BlockIdentifier): Promise<GetBlockResponse>;
     /**
      * Gets the code of the deployed contract.
      *
      * [Reference](https://github.com/starkware-libs/cairo-lang/blob/fc97bdd8322a7df043c87c371634b26c15ed6cee/src/starkware/starknet/services/api/feeder_gateway/feeder_gateway_client.py#L55-L68)
      *
-     * @param contractAddress
-     * @param blockHash
-     * @param blockNumber
+     * @param contractAddress - contract address
+     * @param blockIdentifier - block identifier
      * @returns Bytecode and ABI of compiled contract
      */
-    abstract getCode(contractAddress: string, blockHash?: BigNumberish, blockNumber?: BlockNumber): Promise<GetCodeResponse>;
+    abstract getCode(contractAddress: string, blockIdentifier?: BlockIdentifier): Promise<GetCodeResponse>;
     /**
      * Gets the contract's storage variable at a specific key.
      *
@@ -50,11 +48,10 @@ export declare abstract class ProviderInterface {
      *
      * @param contractAddress
      * @param key - from getStorageVarAddress('<STORAGE_VARIABLE_NAME>') (WIP)
-     * @param blockHash
-     * @param blockNumber
+     * @param blockIdentifier - block identifier
      * @returns the value of the storage variable
      */
-    abstract getStorageAt(contractAddress: string, key: number, blockHash?: BigNumberish, blockNumber?: BlockNumber): Promise<object>;
+    abstract getStorageAt(contractAddress: string, key: number, blockIdentifier?: BlockIdentifier): Promise<object>;
     /**
      * Gets the status of a transaction.
      *

package/dist/provider/utils.d.ts

@@ -15,6 +15,21 @@ export declare function formatHash(): void;
  * @param txId
  */
 export declare function txIdentifier(): void;
+export declare type BlockIdentifier = BlockNumber | BigNumberish;
+declare type BlockIdentifierObject = {
+    type: 'BLOCK_NUMBER';
+    data: BlockNumber;
+} | {
+    type: 'BLOCK_HASH';
+    data: BigNumberish;
+};
+/**
+ * Identifies the block to be queried.
+ *
+ * @param blockIdentifier - block identifier
+ * @returns block identifier object
+ */
+export declare function getBlockIdentifier(blockIdentifier: BlockIdentifier): BlockIdentifierObject;
 /**
  * Gets the block identifier for API request
  *
@@ -24,4 +39,5 @@ export declare function txIdentifier(): void;
  * @param blockHash
  * @returns block identifier for API request
  */
-export declare function getFormattedBlockIdentifier(blockHash?: BigNumberish, blockNumber?: BlockNumber): string;
+export declare function getFormattedBlockIdentifier(blockIdentifier?: BlockIdentifier): string;
+export {};

package/dist/provider/utils.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.getFormattedBlockIdentifier = exports.txIdentifier = exports.formatHash = void 0;
+exports.getFormattedBlockIdentifier = exports.getBlockIdentifier = exports.txIdentifier = exports.formatHash = void 0;
+var number_1 = require("../utils/number");
 /**
  * TODO
  * [Reference](https://github.com/starkware-libs/cairo-lang/blob/fc97bdd8322a7df043c87c371634b26c15ed6cee/src/starkware/starknet/services/api/feeder_gateway/feeder_gateway_client.py#L148-L153)
@@ -18,6 +19,34 @@ exports.formatHash = formatHash;
  */
 function txIdentifier() { }
 exports.txIdentifier = txIdentifier;
+/**
+ * Identifies the block to be queried.
+ *
+ * @param blockIdentifier - block identifier
+ * @returns block identifier object
+ */
+function getBlockIdentifier(blockIdentifier) {
+    if (typeof blockIdentifier === 'number') {
+        return { type: 'BLOCK_NUMBER', data: blockIdentifier };
+    }
+    if (typeof blockIdentifier === 'string' && blockIdentifier.startsWith('0x')) {
+        return { type: 'BLOCK_HASH', data: blockIdentifier };
+    }
+    if (typeof blockIdentifier === 'string' && !Number.isNaN(parseInt(blockIdentifier, 10))) {
+        return { type: 'BLOCK_NUMBER', data: parseInt(blockIdentifier, 10) };
+    }
+    if (blockIdentifier === null) {
+        return { type: 'BLOCK_NUMBER', data: null };
+    }
+    if (blockIdentifier === 'pending') {
+        return { type: 'BLOCK_NUMBER', data: 'pending' };
+    }
+    if (typeof blockIdentifier === 'string') {
+        throw new Error("Invalid block identifier: " + blockIdentifier);
+    }
+    return { type: 'BLOCK_HASH', data: blockIdentifier };
+}
+exports.getBlockIdentifier = getBlockIdentifier;
 /**
  * Gets the block identifier for API request
  *
@@ -27,11 +56,15 @@ exports.txIdentifier = txIdentifier;
  * @param blockHash
  * @returns block identifier for API request
  */
-function getFormattedBlockIdentifier(blockHash, blockNumber) {
-    if (blockNumber === void 0) { blockNumber = null; }
-    if (blockHash) {
-        return "?blockHash=" + blockHash;
+function getFormattedBlockIdentifier(blockIdentifier) {
+    if (blockIdentifier === void 0) { blockIdentifier = null; }
+    var blockIdentifierObject = getBlockIdentifier(blockIdentifier);
+    if (blockIdentifierObject.type === 'BLOCK_NUMBER' && blockIdentifierObject.data === null) {
+        return '';
+    }
+    if (blockIdentifierObject.type === 'BLOCK_NUMBER') {
+        return "?blockNumber=" + blockIdentifierObject.data;
     }
-    return "?blockNumber=" + blockNumber;
+    return "?blockHash=" + (0, number_1.toHex)((0, number_1.toBN)(blockIdentifierObject.data));
 }
 exports.getFormattedBlockIdentifier = getFormattedBlockIdentifier;

package/dist/utils/address.d.ts

@@ -0,0 +1,2 @@
+export declare function addAddressPadding(address: string): string;
+export declare function validateAndParseAddress(address: string): string;

package/dist/utils/address.js

@@ -0,0 +1,22 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateAndParseAddress = exports.addAddressPadding = void 0;
+var constants_1 = require("../constants");
+var encode_1 = require("./encode");
+var number_1 = require("./number");
+function addAddressPadding(address) {
+    return (0, encode_1.addHexPrefix)((0, encode_1.removeHexPrefix)(address).padStart(64, '0'));
+}
+exports.addAddressPadding = addAddressPadding;
+function validateAndParseAddress(address) {
+    if (typeof address !== 'string') {
+        throw new Error('Invalid Address Type');
+    }
+    (0, number_1.assertInRange)(address, constants_1.ZERO, constants_1.MASK_251, 'Starknet Address');
+    var result = addAddressPadding(address);
+    if (!result.match(/^(0x)?[0-9a-fA-F]{64}$/)) {
+        throw new Error('Invalid Address Format');
+    }
+    return result;
+}
+exports.validateAndParseAddress = validateAndParseAddress;

package/index.d.ts

@@ -18,3 +18,4 @@ export * as ec from './utils/ellipticCurve';
 export * as uint256 from './utils/uint256';
 export * as shortString from './utils/shortString';
 export * as typedData from './utils/typedData';
+export * from './utils/address';

package/index.js

@@ -75,3 +75,4 @@ exports.ec = __importStar(require('./utils/ellipticCurve'));
 exports.uint256 = __importStar(require('./utils/uint256'));
 exports.shortString = __importStar(require('./utils/shortString'));
 exports.typedData = __importStar(require('./utils/typedData'));
+__exportStar(require('./utils/address'), exports);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "starknet",
-  "version": "2.8.0",
+  "version": "2.9.0",
   "description": "JavaScript library for StarkNet",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/provider/default.d.ts

@@ -1,6 +1,5 @@
 import {
   AddTransactionResponse,
-  BlockNumber,
   CallContractResponse,
   CallContractTransaction,
   CompiledContract,
@@ -14,6 +13,7 @@ import {
 } from '../types';
 import { BigNumberish } from '../utils/number';
 import { ProviderInterface } from './interface';
+import { BlockIdentifier } from './utils';
 declare type NetworkName = 'mainnet-alpha' | 'goerli-alpha';
 declare type ProviderOptions =
   | {
@@ -49,8 +49,7 @@ export declare class Provider implements ProviderInterface {
    */
   callContract(
     invokeTransaction: CallContractTransaction,
-    blockHash?: BigNumberish,
-    blockNumber?: BlockNumber
+    blockIdentifier?: BlockIdentifier
   ): Promise<CallContractResponse>;
   /**
    * Gets the block information
@@ -61,7 +60,7 @@ export declare class Provider implements ProviderInterface {
    * @param blockNumber
    * @returns the block object { block_number, previous_block_number, state_root, status, timestamp, transaction_receipts, transactions }
    */
-  getBlock(blockHash?: BigNumberish, blockNumber?: BlockNumber): Promise<GetBlockResponse>;
+  getBlock(blockIdentifier?: BlockIdentifier): Promise<GetBlockResponse>;
   /**
    * Gets the code of the deployed contract.
    *
@@ -72,11 +71,7 @@ export declare class Provider implements ProviderInterface {
    * @param blockNumber
    * @returns Bytecode and ABI of compiled contract
    */
-  getCode(
-    contractAddress: string,
-    blockHash?: BigNumberish,
-    blockNumber?: BlockNumber
-  ): Promise<GetCodeResponse>;
+  getCode(contractAddress: string, blockIdentifier?: BlockIdentifier): Promise<GetCodeResponse>;
   /**
    * Gets the contract's storage variable at a specific key.
    *
@@ -91,8 +86,7 @@ export declare class Provider implements ProviderInterface {
   getStorageAt(
     contractAddress: string,
     key: number,
-    blockHash?: BigNumberish,
-    blockNumber?: BlockNumber
+    blockIdentifier?: BlockIdentifier
   ): Promise<object>;
   /**
    * Gets the status of a transaction.

package/provider/default.js

@@ -225,19 +225,16 @@ var Provider = /** @class */ (function () {
    * @param blockNumber
    * @returns the result of the function on the smart contract.
    */
-  Provider.prototype.callContract = function (invokeTransaction, blockHash, blockNumber) {
-    if (blockNumber === void 0) {
-      blockNumber = null;
+  Provider.prototype.callContract = function (invokeTransaction, blockIdentifier) {
+    if (blockIdentifier === void 0) {
+      blockIdentifier = null;
     }
     return __awaiter(this, void 0, void 0, function () {
       var formattedBlockIdentifier, data;
       return __generator(this, function (_a) {
         switch (_a.label) {
           case 0:
-            formattedBlockIdentifier = (0, utils_1.getFormattedBlockIdentifier)(
-              blockHash,
-              blockNumber
-            );
+            formattedBlockIdentifier = (0, utils_1.getFormattedBlockIdentifier)(blockIdentifier);
             return [
               4 /*yield*/,
               axios_1.default.post(
@@ -265,19 +262,16 @@ var Provider = /** @class */ (function () {
    * @param blockNumber
    * @returns the block object { block_number, previous_block_number, state_root, status, timestamp, transaction_receipts, transactions }
    */
-  Provider.prototype.getBlock = function (blockHash, blockNumber) {
-    if (blockNumber === void 0) {
-      blockNumber = null;
+  Provider.prototype.getBlock = function (blockIdentifier) {
+    if (blockIdentifier === void 0) {
+      blockIdentifier = null;
     }
     return __awaiter(this, void 0, void 0, function () {
       var formattedBlockIdentifier, data;
       return __generator(this, function (_a) {
         switch (_a.label) {
           case 0:
-            formattedBlockIdentifier = (0, utils_1.getFormattedBlockIdentifier)(
-              blockHash,
-              blockNumber
-            );
+            formattedBlockIdentifier = (0, utils_1.getFormattedBlockIdentifier)(blockIdentifier);
             return [
               4 /*yield*/,
               axios_1.default.get(
@@ -305,19 +299,16 @@ var Provider = /** @class */ (function () {
    * @param blockNumber
    * @returns Bytecode and ABI of compiled contract
    */
-  Provider.prototype.getCode = function (contractAddress, blockHash, blockNumber) {
-    if (blockNumber === void 0) {
-      blockNumber = null;
+  Provider.prototype.getCode = function (contractAddress, blockIdentifier) {
+    if (blockIdentifier === void 0) {
+      blockIdentifier = null;
     }
     return __awaiter(this, void 0, void 0, function () {
       var formattedBlockIdentifier, data;
       return __generator(this, function (_a) {
         switch (_a.label) {
           case 0:
-            formattedBlockIdentifier = (0, utils_1.getFormattedBlockIdentifier)(
-              blockHash,
-              blockNumber
-            );
+            formattedBlockIdentifier = (0, utils_1.getFormattedBlockIdentifier)(blockIdentifier);
             return [
               4 /*yield*/,
               axios_1.default.get(
@@ -347,19 +338,16 @@ var Provider = /** @class */ (function () {
    * @param blockNumber
    * @returns the value of the storage variable
    */
-  Provider.prototype.getStorageAt = function (contractAddress, key, blockHash, blockNumber) {
-    if (blockNumber === void 0) {
-      blockNumber = null;
+  Provider.prototype.getStorageAt = function (contractAddress, key, blockIdentifier) {
+    if (blockIdentifier === void 0) {
+      blockIdentifier = null;
     }
     return __awaiter(this, void 0, void 0, function () {
       var formattedBlockIdentifier, data;
       return __generator(this, function (_a) {
         switch (_a.label) {
           case 0:
-            formattedBlockIdentifier = (0, utils_1.getFormattedBlockIdentifier)(
-              blockHash,
-              blockNumber
-            );
+            formattedBlockIdentifier = (0, utils_1.getFormattedBlockIdentifier)(blockIdentifier);
             return [
               4 /*yield*/,
               axios_1.default.get(

package/provider/interface.d.ts

@@ -1,6 +1,5 @@
 import type {
   AddTransactionResponse,
-  BlockNumber,
   CallContractResponse,
   CallContractTransaction,
   CompiledContract,
@@ -13,6 +12,7 @@ import type {
   Transaction,
 } from '../types';
 import type { BigNumberish } from '../utils/number';
+import { BlockIdentifier } from './utils';
 export declare abstract class ProviderInterface {
   abstract baseUrl: string;
   abstract feederGatewayUrl: string;
@@ -30,39 +30,34 @@ export declare abstract class ProviderInterface {
    * [Reference](https://github.com/starkware-libs/cairo-lang/blob/fc97bdd8322a7df043c87c371634b26c15ed6cee/src/starkware/starknet/services/api/feeder_gateway/feeder_gateway_client.py#L25-L39)
    *
    * @param invokeTransaction - transaction to be invoked
-   * @param blockHash
-   * @param blockNumber
+   * @param blockIdentifier - block identifier
    * @returns the result of the function on the smart contract.
    */
   abstract callContract(
     invokeTransaction: CallContractTransaction,
-    blockHash?: BigNumberish,
-    blockNumber?: BlockNumber
+    blockIdentifier?: BlockIdentifier
   ): Promise<CallContractResponse>;
   /**
    * Gets the block information
    *
    * [Reference](https://github.com/starkware-libs/cairo-lang/blob/fc97bdd8322a7df043c87c371634b26c15ed6cee/src/starkware/starknet/services/api/feeder_gateway/feeder_gateway_client.py#L41-L53)
    *
-   * @param blockHash
-   * @param blockNumber
+   * @param blockIdentifier - block identifier
    * @returns the block object { block_number, previous_block_number, state_root, status, timestamp, transaction_receipts, transactions }
    */
-  abstract getBlock(blockHash?: BigNumberish, blockNumber?: BlockNumber): Promise<GetBlockResponse>;
+  abstract getBlock(blockIdentifier?: BlockIdentifier): Promise<GetBlockResponse>;
   /**
    * Gets the code of the deployed contract.
    *
    * [Reference](https://github.com/starkware-libs/cairo-lang/blob/fc97bdd8322a7df043c87c371634b26c15ed6cee/src/starkware/starknet/services/api/feeder_gateway/feeder_gateway_client.py#L55-L68)
    *
-   * @param contractAddress
-   * @param blockHash
-   * @param blockNumber
+   * @param contractAddress - contract address
+   * @param blockIdentifier - block identifier
    * @returns Bytecode and ABI of compiled contract
    */
   abstract getCode(
     contractAddress: string,
-    blockHash?: BigNumberish,
-    blockNumber?: BlockNumber
+    blockIdentifier?: BlockIdentifier
   ): Promise<GetCodeResponse>;
   /**
    * Gets the contract's storage variable at a specific key.
@@ -71,15 +66,13 @@ export declare abstract class ProviderInterface {
    *
    * @param contractAddress
    * @param key - from getStorageVarAddress('<STORAGE_VARIABLE_NAME>') (WIP)
-   * @param blockHash
-   * @param blockNumber
+   * @param blockIdentifier - block identifier
    * @returns the value of the storage variable
    */
   abstract getStorageAt(
     contractAddress: string,
     key: number,
-    blockHash?: BigNumberish,
-    blockNumber?: BlockNumber
+    blockIdentifier?: BlockIdentifier
   ): Promise<object>;
   /**
    * Gets the status of a transaction.

package/provider/utils.d.ts

@@ -15,6 +15,23 @@ export declare function formatHash(): void;
  * @param txId
  */
 export declare function txIdentifier(): void;
+export declare type BlockIdentifier = BlockNumber | BigNumberish;
+declare type BlockIdentifierObject =
+  | {
+      type: 'BLOCK_NUMBER';
+      data: BlockNumber;
+    }
+  | {
+      type: 'BLOCK_HASH';
+      data: BigNumberish;
+    };
+/**
+ * Identifies the block to be queried.
+ *
+ * @param blockIdentifier - block identifier
+ * @returns block identifier object
+ */
+export declare function getBlockIdentifier(blockIdentifier: BlockIdentifier): BlockIdentifierObject;
 /**
  * Gets the block identifier for API request
  *
@@ -24,7 +41,5 @@ export declare function txIdentifier(): void;
  * @param blockHash
  * @returns block identifier for API request
  */
-export declare function getFormattedBlockIdentifier(
-  blockHash?: BigNumberish,
-  blockNumber?: BlockNumber
-): string;
+export declare function getFormattedBlockIdentifier(blockIdentifier?: BlockIdentifier): string;
+export {};

package/provider/utils.js

@@ -1,6 +1,11 @@
 'use strict';
 Object.defineProperty(exports, '__esModule', { value: true });
-exports.getFormattedBlockIdentifier = exports.txIdentifier = exports.formatHash = void 0;
+exports.getFormattedBlockIdentifier =
+  exports.getBlockIdentifier =
+  exports.txIdentifier =
+  exports.formatHash =
+    void 0;
+var number_1 = require('../utils/number');
 /**
  * TODO
  * [Reference](https://github.com/starkware-libs/cairo-lang/blob/fc97bdd8322a7df043c87c371634b26c15ed6cee/src/starkware/starknet/services/api/feeder_gateway/feeder_gateway_client.py#L148-L153)
@@ -18,6 +23,34 @@ exports.formatHash = formatHash;
  */
 function txIdentifier() {}
 exports.txIdentifier = txIdentifier;
+/**
+ * Identifies the block to be queried.
+ *
+ * @param blockIdentifier - block identifier
+ * @returns block identifier object
+ */
+function getBlockIdentifier(blockIdentifier) {
+  if (typeof blockIdentifier === 'number') {
+    return { type: 'BLOCK_NUMBER', data: blockIdentifier };
+  }
+  if (typeof blockIdentifier === 'string' && blockIdentifier.startsWith('0x')) {
+    return { type: 'BLOCK_HASH', data: blockIdentifier };
+  }
+  if (typeof blockIdentifier === 'string' && !Number.isNaN(parseInt(blockIdentifier, 10))) {
+    return { type: 'BLOCK_NUMBER', data: parseInt(blockIdentifier, 10) };
+  }
+  if (blockIdentifier === null) {
+    return { type: 'BLOCK_NUMBER', data: null };
+  }
+  if (blockIdentifier === 'pending') {
+    return { type: 'BLOCK_NUMBER', data: 'pending' };
+  }
+  if (typeof blockIdentifier === 'string') {
+    throw new Error('Invalid block identifier: ' + blockIdentifier);
+  }
+  return { type: 'BLOCK_HASH', data: blockIdentifier };
+}
+exports.getBlockIdentifier = getBlockIdentifier;
 /**
  * Gets the block identifier for API request
  *
@@ -27,13 +60,17 @@ exports.txIdentifier = txIdentifier;
  * @param blockHash
  * @returns block identifier for API request
  */
-function getFormattedBlockIdentifier(blockHash, blockNumber) {
-  if (blockNumber === void 0) {
-    blockNumber = null;
+function getFormattedBlockIdentifier(blockIdentifier) {
+  if (blockIdentifier === void 0) {
+    blockIdentifier = null;
+  }
+  var blockIdentifierObject = getBlockIdentifier(blockIdentifier);
+  if (blockIdentifierObject.type === 'BLOCK_NUMBER' && blockIdentifierObject.data === null) {
+    return '';
   }
-  if (blockHash) {
-    return '?blockHash=' + blockHash;
+  if (blockIdentifierObject.type === 'BLOCK_NUMBER') {
+    return '?blockNumber=' + blockIdentifierObject.data;
   }
-  return '?blockNumber=' + blockNumber;
+  return '?blockHash=' + (0, number_1.toHex)((0, number_1.toBN)(blockIdentifierObject.data));
 }
 exports.getFormattedBlockIdentifier = getFormattedBlockIdentifier;

package/src/constants.ts

@@ -6,6 +6,7 @@ export const ZERO = toBN(0);
 export const ONE = toBN(1);
 export const TWO = toBN(2);
 export const MASK_250 = TWO.pow(toBN(250)).sub(ONE); // 2 ** 250 - 1
+export const MASK_251 = TWO.pow(toBN(251));
 
 /**
  * The following is taken from https://github.com/starkware-libs/starkex-resources/blob/master/crypto/starkware/crypto/signature/pedersen_params.json but converted to hex, because JS is very bad handling big integers by default
@@ -13,6 +14,7 @@ export const MASK_250 = TWO.pow(toBN(250)).sub(ONE); // 2 ** 250 - 1
  */
 export const FIELD_PRIME = '800000000000011000000000000000000000000000000000000000000000001';
 export const FIELD_GEN = '3';
+export const FIELD_SIZE = 251;
 export const EC_ORDER = '800000000000010FFFFFFFFFFFFFFFFB781126DCAE7B2321E66A241ADC64D2F';
 export const ALPHA = '1';
 export const BETA = '6F21413EFBE40DE150E596D72F7A8C5609AD26C15C915C1F4CDFCB99CEE9E89';

package/src/index.ts

@@ -19,3 +19,4 @@ export * as ec from './utils/ellipticCurve';
 export * as uint256 from './utils/uint256';
 export * as shortString from './utils/shortString';
 export * as typedData from './utils/typedData';
+export * from './utils/address';

package/src/provider/default.ts

@@ -3,7 +3,6 @@ import urljoin from 'url-join';
 
 import {
   AddTransactionResponse,
-  BlockNumber,
   CallContractResponse,
   CallContractTransaction,
   CompiledContract,
@@ -19,7 +18,7 @@ import { parse, stringify } from '../utils/json';
 import { BigNumberish, toBN, toHex } from '../utils/number';
 import { compressProgram, formatSignature, randomAddress } from '../utils/stark';
 import { ProviderInterface } from './interface';
-import { getFormattedBlockIdentifier } from './utils';
+import { BlockIdentifier, getFormattedBlockIdentifier } from './utils';
 
 type NetworkName = 'mainnet-alpha' | 'goerli-alpha';
 
@@ -93,10 +92,9 @@ export class Provider implements ProviderInterface {
    */
   public async callContract(
     invokeTransaction: CallContractTransaction,
-    blockHash?: BigNumberish,
-    blockNumber: BlockNumber = null
+    blockIdentifier: BlockIdentifier = null
   ): Promise<CallContractResponse> {
-    const formattedBlockIdentifier = getFormattedBlockIdentifier(blockHash, blockNumber);
+    const formattedBlockIdentifier = getFormattedBlockIdentifier(blockIdentifier);
 
     const { data } = await axios.post<CallContractResponse>(
       urljoin(this.feederGatewayUrl, 'call_contract', formattedBlockIdentifier),
@@ -118,11 +116,8 @@ export class Provider implements ProviderInterface {
    * @param blockNumber
    * @returns the block object { block_number, previous_block_number, state_root, status, timestamp, transaction_receipts, transactions }
    */
-  public async getBlock(
-    blockHash?: BigNumberish,
-    blockNumber: BlockNumber = null
-  ): Promise<GetBlockResponse> {
-    const formattedBlockIdentifier = getFormattedBlockIdentifier(blockHash, blockNumber);
+  public async getBlock(blockIdentifier: BlockIdentifier = null): Promise<GetBlockResponse> {
+    const formattedBlockIdentifier = getFormattedBlockIdentifier(blockIdentifier);
 
     const { data } = await axios.get<GetBlockResponse>(
       urljoin(this.feederGatewayUrl, 'get_block', formattedBlockIdentifier)
@@ -142,10 +137,9 @@ export class Provider implements ProviderInterface {
    */
   public async getCode(
     contractAddress: string,
-    blockHash?: BigNumberish,
-    blockNumber: BlockNumber = null
+    blockIdentifier: BlockIdentifier = null
   ): Promise<GetCodeResponse> {
-    const formattedBlockIdentifier = getFormattedBlockIdentifier(blockHash, blockNumber);
+    const formattedBlockIdentifier = getFormattedBlockIdentifier(blockIdentifier);
 
     const { data } = await axios.get<GetCodeResponse>(
       urljoin(
@@ -172,10 +166,9 @@ export class Provider implements ProviderInterface {
   public async getStorageAt(
     contractAddress: string,
     key: number,
-    blockHash?: BigNumberish,
-    blockNumber: BlockNumber = null
+    blockIdentifier: BlockIdentifier = null
   ): Promise<object> {
-    const formattedBlockIdentifier = getFormattedBlockIdentifier(blockHash, blockNumber);
+    const formattedBlockIdentifier = getFormattedBlockIdentifier(blockIdentifier);
 
     const { data } = await axios.get<object>(
       urljoin(

package/src/provider/interface.ts

@@ -1,6 +1,5 @@
 import type {
   AddTransactionResponse,
-  BlockNumber,
   CallContractResponse,
   CallContractTransaction,
   CompiledContract,
@@ -13,6 +12,7 @@ import type {
   Transaction,
 } from '../types';
 import type { BigNumberish } from '../utils/number';
+import { BlockIdentifier } from './utils';
 
 export abstract class ProviderInterface {
   public abstract baseUrl: string;
@@ -35,14 +35,12 @@ export abstract class ProviderInterface {
    * [Reference](https://github.com/starkware-libs/cairo-lang/blob/fc97bdd8322a7df043c87c371634b26c15ed6cee/src/starkware/starknet/services/api/feeder_gateway/feeder_gateway_client.py#L25-L39)
    *
    * @param invokeTransaction - transaction to be invoked
-   * @param blockHash
-   * @param blockNumber
+   * @param blockIdentifier - block identifier
    * @returns the result of the function on the smart contract.
    */
   public abstract callContract(
     invokeTransaction: CallContractTransaction,
-    blockHash?: BigNumberish,
-    blockNumber?: BlockNumber
+    blockIdentifier?: BlockIdentifier
   ): Promise<CallContractResponse>;
 
   /**
@@ -50,29 +48,23 @@ export abstract class ProviderInterface {
    *
    * [Reference](https://github.com/starkware-libs/cairo-lang/blob/fc97bdd8322a7df043c87c371634b26c15ed6cee/src/starkware/starknet/services/api/feeder_gateway/feeder_gateway_client.py#L41-L53)
    *
-   * @param blockHash
-   * @param blockNumber
+   * @param blockIdentifier - block identifier
    * @returns the block object { block_number, previous_block_number, state_root, status, timestamp, transaction_receipts, transactions }
    */
-  public abstract getBlock(
-    blockHash?: BigNumberish,
-    blockNumber?: BlockNumber
-  ): Promise<GetBlockResponse>;
+  public abstract getBlock(blockIdentifier?: BlockIdentifier): Promise<GetBlockResponse>;
 
   /**
    * Gets the code of the deployed contract.
    *
    * [Reference](https://github.com/starkware-libs/cairo-lang/blob/fc97bdd8322a7df043c87c371634b26c15ed6cee/src/starkware/starknet/services/api/feeder_gateway/feeder_gateway_client.py#L55-L68)
    *
-   * @param contractAddress
-   * @param blockHash
-   * @param blockNumber
+   * @param contractAddress - contract address
+   * @param blockIdentifier - block identifier
    * @returns Bytecode and ABI of compiled contract
    */
   public abstract getCode(
     contractAddress: string,
-    blockHash?: BigNumberish,
-    blockNumber?: BlockNumber
+    blockIdentifier?: BlockIdentifier
   ): Promise<GetCodeResponse>;
 
   // TODO: add proper type
@@ -83,15 +75,13 @@ export abstract class ProviderInterface {
    *
    * @param contractAddress
    * @param key - from getStorageVarAddress('<STORAGE_VARIABLE_NAME>') (WIP)
-   * @param blockHash
-   * @param blockNumber
+   * @param blockIdentifier - block identifier
    * @returns the value of the storage variable
    */
   public abstract getStorageAt(
     contractAddress: string,
     key: number,
-    blockHash?: BigNumberish,
-    blockNumber?: BlockNumber
+    blockIdentifier?: BlockIdentifier
   ): Promise<object>;
 
   /**

package/src/provider/utils.ts

@@ -1,5 +1,5 @@
 import type { BlockNumber } from '../types';
-import { BigNumberish } from '../utils/number';
+import { BigNumberish, toBN, toHex } from '../utils/number';
 
 /**
  * TODO
@@ -18,6 +18,42 @@ export function formatHash() {}
  */
 export function txIdentifier() {}
 
+// hex string and BN are detected as block hashes
+// decimal string and number are detected as block numbers
+// null appends nothing to the request url
+export type BlockIdentifier = BlockNumber | BigNumberish;
+type BlockIdentifierObject =
+  | { type: 'BLOCK_NUMBER'; data: BlockNumber }
+  | { type: 'BLOCK_HASH'; data: BigNumberish };
+
+/**
+ * Identifies the block to be queried.
+ *
+ * @param blockIdentifier - block identifier
+ * @returns block identifier object
+ */
+export function getBlockIdentifier(blockIdentifier: BlockIdentifier): BlockIdentifierObject {
+  if (typeof blockIdentifier === 'number') {
+    return { type: 'BLOCK_NUMBER', data: blockIdentifier };
+  }
+  if (typeof blockIdentifier === 'string' && blockIdentifier.startsWith('0x')) {
+    return { type: 'BLOCK_HASH', data: blockIdentifier };
+  }
+  if (typeof blockIdentifier === 'string' && !Number.isNaN(parseInt(blockIdentifier, 10))) {
+    return { type: 'BLOCK_NUMBER', data: parseInt(blockIdentifier, 10) };
+  }
+  if (blockIdentifier === null) {
+    return { type: 'BLOCK_NUMBER', data: null };
+  }
+  if (blockIdentifier === 'pending') {
+    return { type: 'BLOCK_NUMBER', data: 'pending' };
+  }
+  if (typeof blockIdentifier === 'string') {
+    throw new Error(`Invalid block identifier: ${blockIdentifier}`);
+  }
+  return { type: 'BLOCK_HASH', data: blockIdentifier };
+}
+
 /**
  * Gets the block identifier for API request
  *
@@ -27,12 +63,13 @@ export function txIdentifier() {}
  * @param blockHash
  * @returns block identifier for API request
  */
-export function getFormattedBlockIdentifier(
-  blockHash?: BigNumberish,
-  blockNumber: BlockNumber = null
-): string {
-  if (blockHash) {
-    return `?blockHash=${blockHash}`;
-  }
-  return `?blockNumber=${blockNumber}`;
+export function getFormattedBlockIdentifier(blockIdentifier: BlockIdentifier = null): string {
+  const blockIdentifierObject = getBlockIdentifier(blockIdentifier);
+  if (blockIdentifierObject.type === 'BLOCK_NUMBER' && blockIdentifierObject.data === null) {
+    return '';
+  }
+  if (blockIdentifierObject.type === 'BLOCK_NUMBER') {
+    return `?blockNumber=${blockIdentifierObject.data}`;
+  }
+  return `?blockHash=${toHex(toBN(blockIdentifierObject.data))}`;
 }

package/src/utils/address.ts

@@ -0,0 +1,23 @@
+import { MASK_251, ZERO } from '../constants';
+import { addHexPrefix, removeHexPrefix } from './encode';
+import { assertInRange } from './number';
+
+export function addAddressPadding(address: string): string {
+  return addHexPrefix(removeHexPrefix(address).padStart(64, '0'));
+}
+
+export function validateAndParseAddress(address: string): string {
+  if (typeof address !== 'string') {
+    throw new Error('Invalid Address Type');
+  }
+
+  assertInRange(address, ZERO, MASK_251, 'Starknet Address');
+
+  const result = addAddressPadding(address);
+
+  if (!result.match(/^(0x)?[0-9a-fA-F]{64}$/)) {
+    throw new Error('Invalid Address Format');
+  }
+
+  return result;
+}

package/utils/address.d.ts

@@ -0,0 +1,2 @@
+export declare function addAddressPadding(address: string): string;
+export declare function validateAndParseAddress(address: string): string;

package/utils/address.js

@@ -0,0 +1,22 @@
+'use strict';
+Object.defineProperty(exports, '__esModule', { value: true });
+exports.validateAndParseAddress = exports.addAddressPadding = void 0;
+var constants_1 = require('../constants');
+var encode_1 = require('./encode');
+var number_1 = require('./number');
+function addAddressPadding(address) {
+  return (0, encode_1.addHexPrefix)((0, encode_1.removeHexPrefix)(address).padStart(64, '0'));
+}
+exports.addAddressPadding = addAddressPadding;
+function validateAndParseAddress(address) {
+  if (typeof address !== 'string') {
+    throw new Error('Invalid Address Type');
+  }
+  (0, number_1.assertInRange)(address, constants_1.ZERO, constants_1.MASK_251, 'Starknet Address');
+  var result = addAddressPadding(address);
+  if (!result.match(/^(0x)?[0-9a-fA-F]{64}$/)) {
+    throw new Error('Invalid Address Format');
+  }
+  return result;
+}
+exports.validateAndParseAddress = validateAndParseAddress;