starknet 4.2.0 → 4.4.0

package/www/docs/API/provider.md

@@ -4,7 +4,7 @@ sidebar_position: 1
 
 # Provider
 
-The **Provider** API allows you to interface with the StarkNet network, without signing transactions or messages.
+The **Provider** API allows you to interact with the StarkNet network, without signing transactions or messages.
 
 Typically, these are _read_ calls on the blockchain.
 
@@ -12,14 +12,32 @@ Typically, these are _read_ calls on the blockchain.
 
 `new starknet.Provider(optionsOrProvider)`
 
-The options for the provider depends from the network. The structure of the options object is:
+The options for the provider depend on the network. The structure of the options object is:
 
 - options.**sequencer** - Options for sequencer provider
 - options.**rpc** - Options for RPC provider
 
-Example:
+The easiest way to get started is:
+
+```typescript
+const provider = new starknet.Provider()
+```
+
+The above snippet creates a Starknet Provider instance with `goerli-alpha` network.
 
+However, if you want to use `mainnet-alpha` or explicitly declare the network, you can use:
+
+```typescript
+const provider = new starknet.Provider({
+  sequencer: {
+    network: 'mainnet-alpha' // or 'goerli-alpha'
+  }
+})
 ```
+
+If you want more control:
+
+```typescript
 const provider = new starknet.Provider({
   sequencer: {
     baseUrl: 'https://alpha4.starknet.io',
@@ -29,7 +47,11 @@ const provider = new starknet.Provider({
 })
 ```
 
-**This is also default options for the constructor for the **testnet\*\*\*
+These are also the default options for the Provider constructor with `network: 'goerli-alpha'`.
+
+> **Note**
+>
+> `network` arguement should work in most cases. If you want to use the `sequencer` arguement with `baseUrl`, you will not be able to use the `network` field in the object.
 
 ## Methods
 
@@ -43,13 +65,13 @@ The call object structure:
 
 - call.**contractAddress** - Address of the contract
 - call.**entrypoint** - Entrypoint of the call (method name)
-- call.**calldata** - Payload for the invoking the method
+- call.**calldata** - Payload for the invoking method
 
-###### CallContractResponse
+###### _CallContractResponse_
 
-```
+```typescript
 {
-    result: string[];
+  result: string[];
 }
 ```
 
@@ -61,7 +83,7 @@ Gets the block information.
 
 ###### _GetBlockResponse_
 
-```
+```typescript
 {
   accepted_time: number;
   block_hash: string;
@@ -85,7 +107,7 @@ Gets the contract class of the deployed contract.
 
 ###### _ContractClass_
 
-```
+```typescript
 {
   program: CompressedProgram;
   entry_points_by_type: EntryPointsByType;
@@ -95,9 +117,9 @@ Gets the contract class of the deployed contract.
 
 <hr/>
 
-provider.**getStorageAt**(contractAddress, key, blockHashOrTag) => _Promise < string >_
+provider.**getStorageAt**(contractAddress, key, blockIdentifier) => _Promise < string >_
 
-Gets the contract's storage variable at a specific key
+Gets the contract's storage variable at a specific key.
 
 <hr/>
 
@@ -107,7 +129,7 @@ Gets the status of a transaction.
 
 ###### _GetTransactionReceiptResponse_
 
-```
+```typescript
 {
   transaction_hash: string;
   status: 'NOT_RECEIVED' | 'RECEIVED' | 'PENDING' | 'ACCEPTED_ON_L2' | 'ACCEPTED_ON_L1' | 'REJECTED';
@@ -127,7 +149,7 @@ Gets the transaction information from a tx hash.
 
 ###### _GetTransactionResponse_
 
-```
+```typescript
 {
   transaction_hash: string;
   version?: string;
@@ -146,27 +168,26 @@ Gets the transaction information from a tx hash.
 
 provider.**declareContract**(payload) => _Promise < DeclareContractResponse >_
 
-Declares a contract on Starknet
+Declares a contract on Starknet.
 
 ###### _DeclareContractResponse_
 
-```
+```typescript
 {
   transaction_hash: string;
   class_hash: string;
 };
+```
 
 <hr/>
 
-```
-
 provider.**deployContract**(payload [ , abi ]) => _Promise < DeployContractResponse >_
 
-Deploys a contract on Starknet
+Deploys a contract on Starknet.
 
 ###### _DeployContractResponse_
 
-```
+```typescript
 {
   transaction_hash: string;
   contract_address?: string;
@@ -185,7 +206,7 @@ Wait for the transaction to be accepted on L2 or L1.
 
 `new starknet.SequencerProvider(optionsOrProvider)`
 
-The options for the provider depends from the network. The structure of the options object is:
+The options for the provider depend on the network. The structure of the options object is:
 
 - options.**baseUrl** - Base URL of the network
 - options.**feederGatewayUrl** - Feeder Gateway Endpoint of the network
@@ -193,11 +214,11 @@ The options for the provider depends from the network. The structure of the opti
 
 or
 
-- options.**network** - One of 'mainnet-alpha' or 'goerli-alpha'
+- options.**network** - Either 'mainnet-alpha' or 'goerli-alpha'
 
 Example:
 
-```
+```typescript
 const provider = new starknet.Provider({
   baseUrl: 'https://alpha4.starknet.io',
   feederGatewayUrl: 'feeder_gateway',
@@ -207,11 +228,13 @@ const provider = new starknet.Provider({
 
 ## Methods
 
-Gets the smart contract address on the network
+Gets the smart contract address on the network.
 
 provider.**getContractAddresses**() => _Promise < GetContractAddressesResponse >_
 
-```
+###### _GetContractAddressesResponse_
+
+```typescript
 {
   Starknet: string;
   GpsStatementVerifier: string;
@@ -226,7 +249,7 @@ Gets the status of a transaction.
 
 ###### _GetTransactionStatusResponse_
 
-```
+```typescript
 {
   tx_status: 'NOT_RECEIVED' | 'RECEIVED' | 'PENDING' | 'ACCEPTED_ON_L2' | 'ACCEPTED_ON_L1' | 'REJECTED';
   block_hash: string;
@@ -246,7 +269,7 @@ Gets the transaction trace from a tx hash.
 
 ###### _GetTransactionTraceResponse_
 
-```
+```typescript
 {
   function_invocation: {
     caller_address: string;
@@ -254,7 +277,7 @@ Gets the transaction trace from a tx hash.
     code_address: string;
     selector: string;
     calldata: {
-        [inputName: string]: string | string[] | { type: 'struct'; [k: string]: BigNumberish };
+      [inputName: string]: string | string[] | { type: 'struct'; [k: string]: BigNumberish };
     };
     result: Array<any>;
     execution_resources: any;
@@ -276,7 +299,7 @@ Gets the transaction trace from a tx hash.
 
 Example:
 
-```
+```typescript
 const provider = new starknet.RpcProvider({
   nodeUrl: 'URL_TO_STARKNET_RPC_NODE',
 })
@@ -292,17 +315,17 @@ Gets the transaction count from a block.
 
 provider.**getBlockNumber**() => _Promise < number >_
 
-Gets the latest block number
+Gets the latest block number.
 
 <hr/>
 
 provider.**getSyncingStats**() => _Promise < GetSyncingStatsResponse >_
 
-Gets syncing status of the node
+Gets syncing status of the node.
 
-###### GetSyncingStatsResponse
+###### _GetSyncingStatsResponse_
 
-```
+```typescript
 boolean |
 {
   starting_block_hash: string;
@@ -318,9 +341,9 @@ boolean |
 
 provider.**getEvents**(eventFilter) => _Promise < GetEventsResponse >_
 
-##### EventFilter
+##### _EventFilter_
 
-```
+```typescript
 type EventFilter = {
   fromBlock: string;
   toBlock: string;
@@ -331,9 +354,9 @@ type EventFilter = {
 };
 ```
 
-###### GetSyncingStatsResponse
+###### _GetEventsResponse_
 
-```
+```typescript
 {
   events: StarknetEmittedEvent[];
   page_number: number;

package/www/docs/API/signer.md

@@ -10,21 +10,21 @@ The **Signer** API allows you to sign transactions and messages, and also allows
 
 `new starknet.Signer(keyPair)`
 
-## Signer Methods
+## Methods
 
 signer.**getPubKey**() => _Promise < string >_
 
-Returns public key of the signer
+Returns the public key of the signer.
 
 <hr />
 
 signer.**signTransaction**(transactions, transactionsDetail [ , abi ]) => _Promise < Signature >_
 
-Returns signature of the transaction
+Returns the signature of the transaction.
 
-###### Signature
+###### _Signature_
 
-```
+```typescript
 string[]
 ```
 
@@ -32,12 +32,10 @@ string[]
 
 signer.**signMessage**(typedData, accountAddress) => _Promise < Signature >_
 
-Returns signature of the transaction
+Returns the signature of the transaction.
 
-###### Signature
+###### _Signature_
 
-```
+```typescript
 string[]
 ```
-
-<hr />

package/www/docs/API/utils.md

@@ -4,19 +4,21 @@ sidebar_position: 6
 
 # Utils
 
-Util functions are provided so you can use low level functions in your application.
+Util functions are provided so you can use various low level functions in your application.
 
-## `address`
+## **address**
 
-the address helpers can be imported using:
+Helper functions for starknet addresses.
 
-```js
-import { address } from 'starknet.js';
-```
+### validateAndParseAddress
 
-<br/>
+`validateAndParseAddress(address: BigNumberish): string`
 
-### `getChecksumAddress(address: BigNumberish): string`
+Checks if the address is valid and, if it is, parses it to the correct format (0x prefix is added if not provided).
+
+### getChecksumAddress
+
+`getChecksumAddress(address: BigNumberish): string`
 
 This function accepts an address as a `BigNumberish` and returns the checksummed address as a string.
 An example:
@@ -31,47 +33,53 @@ const checksummedAddress = address.getChecksumAddress(addressToCheck);
 console.log(checksummedAddress); // 0x02FD23D9182193775423497Fc0c472E156C57C69E4089a1967fb288a2D84e914
 ```
 
-<br/>
+### validateChecksumAddress
+
+`validateChecksumAddress(address: string): boolean`
 
-### `validateChecksumAddress(address: string): boolean`
+This function validates the checksum address.
 
-This function validates the checksum address. It returns true if the address is valid, false otherwise.
+Returns true if the address is valid, false otherwise.
 
 <hr />
 
-## `stark`
+## **stark**
 
 Functions for stark specific manipulations.
 
-<br/>
+### compressProgram
 
-### `compressProgram(jsonProgram: Program | string): CompressedProgram`
+`compressProgram(jsonProgram: Program | string): CompressedProgram`
 
 Function to compress compiled cairo program. Accepts a json file representing the compiled cairo program and returns a compressed cairo program.
 
-<br/>
+### randomAddress
 
-### `randomAddress(): string`
+`randomAddress(): string`
 
-Function that generates a random contract address.
+Function that generates a random stark address.
 
-<br/>
+### makeAddress
 
-### `makeAddress(input: string): string`
+`makeAddress(input: string): string`
 
-Function that turns an incompatible address string into stark address format. Returns a string.
+Function that turns an incompatible address string into stark address format.
+
+Returns a string.
 
 Example: `0xdFD0F27FCe99b50909de0bDD328Aed6eAbe76BC5` -> `0xdfd0f27fce99b50909de0bdd328aed6eabe76bc5`
 
-<br/>
+### formatSignature
+
+`formatSignature(sig?: Signature): string[]`
 
-### `formatSignature(sig?: Signature): string[]`
+Function that formats a Signature to BigNum and then to string array.
 
-Function that formats a Signature to BigNum and then to string array. Returns a string array.
+Returns a string array.
 
-<br/>
+### compileCalldata
 
-### `compileCalldata(args: RawArgs): Calldata`
+`compileCalldata(args: RawArgs): Calldata`
 
 Function that creates calldata that gets sent to the contract.
 
@@ -86,9 +94,9 @@ await this.callContract({
 });
 ```
 
-<br/>
+### estimatedFeeToMaxFee
 
-### `estimatedFeeToMaxFee(estimatedFee: BigNumberish, overhead: number = 0.5): BN`
+`estimatedFeeToMaxFee(estimatedFee: BigNumberish, overhead: number = 0.5): BN`
 
 Function that calculates and returns maximum fee based on the previously estimated one.
 
@@ -96,7 +104,7 @@ Returns a BN.
 
 <hr />
 
-## `number`
+## **number**
 
 Various number formatting functions.
 
@@ -106,47 +114,53 @@ Various number formatting functions.
 export type BigNumberish = string | number | BN;
 ```
 
-<br/>
+### isHex
 
-### `isHex(hex: string): boolean`
+`isHex(hex: string): boolean`
 
 Check if number is in hex format.
 
-<br/>
+### toBN
+
+`toBN(number: BigNumberish, base?: number | 'hex'): BN`
 
-### `toBN(number: BigNumberish, base?: number | 'hex'): BN`
+Converts BigNumberish to BN.
 
-Converts BigNumberish to BN. Returns a BN.
+Returns a BN.
+
+### toHex
 
-<br/>
+`toHex(number: BN): string`
 
-### `toHex(number: BN): string`
+Converts BN to hex.
 
-Converts BN to hex. Returns a string.
+Returns a string.
 
-<br/>
+### hexToDecimalString
 
-### `hexToDecimalString(hex: string): string`
+`hexToDecimalString(hex: string): string`
 
 Converts hex string to decimal string.
 
-<br/>
+### toFelt
+
+`toFelt(num: BigNumberish): string`
 
-### `toFelt(num: BigNumberish): string`
+Converts BN to Felt.
 
-Converts BN to Felt. Returns a string.
+Returns a string.
 
-<br/>
+### assertInRange
 
-### `assertInRange(input: BigNumberish, lowerBound: BigNumberish, upperBound: BigNumberish, inputName = '')`
+`assertInRange(input: BigNumberish, lowerBound: BigNumberish, upperBound: BigNumberish, inputName = '')`
 
 Asserts input is equal to or greater then `lowerBound` and lower then `upperBound`. Assert message specifies inputName.
 `input`, `lowerBound`, and `upperBound` should be of type BN.
 `inputName` should be a string.
 
-<br/>
+### bigNumberishArrayToDecimalStringArray
 
-### `bigNumberishArrayToDecimalStringArray(rawCalldata: BigNumberish[]): string[]`
+`bigNumberishArrayToDecimalStringArray(rawCalldata: BigNumberish[]): string[]`
 
 Convert BigNumberish array to decimal array. Used for signature conversion.
 
@@ -164,7 +178,7 @@ const signature = await this.signer.signTransaction(transactions, signerDetails)
 
 <hr />
 
-## `uint256`
+## **uint256**
 
 ```js
 // Represents an integer in the range [0, 2^256).
@@ -176,74 +190,81 @@ export interface Uint256 {
 }
 ```
 
-<br/>
+### uint256ToBN
 
-### `uint256ToBN(uint256: Uint256): BN`
+`uint256ToBN(uint256: Uint256): BN`
 
 Function to convert `Uint256` to `BN` (big number), which uses the `bn.js` library.
 
-<br/>
+### isUint256
 
-### `isUint256(bn: BigNumberish): boolean`
+`isUint256(bn: BigNumberish): boolean`
 
 Function to check if `BN` is smaller or equal to `2**256-1`.
 
-<br/>
+### bnToUint256
 
-### `bnToUint256(bignumber: BigNumberish): Uint256`
+`bnToUint256(bignumber: BigNumberish): Uint256`
 
 Function to convert `BN` to `Uint256`.
 
 <hr />
 
-## `hash`
+## **hash**
 
 Various hashing helpers.
 
-### `starknetKeccak(value: string): BN`
+### starknetKeccak
+
+`starknetKeccak(value: string): BN`
 
 Function to get the starknet keccak hash from a string. Returns starknet keccak hash as BigNumber.
-nction to get the starknet keccak hash from a string. Returns starknet keccak hash as BigNumber.
 
-<br/>
+Returns starknet keccak hash as BigNumber.
+
+### getSelectorFromName
+
+`getSelectorFromName(funcName: string)`
 
-### `getSelectorFromName(funcName: string)`
+Function to get the hex selector from a given function name.
 
-Function to get the hex selector from a given function name. Returns hex selector of given abi function name.
+Returns hex selector of given abi function name.
 
-<br/>
+### pedersen
 
-### `pedersen(input: [BigNumberish, BigNumberish])`
+`pedersen(input: [BigNumberish, BigNumberish])`
 
-<br/>
+Function to get the Pedersen hash for two arguments.
 
-Function to get the Pedersen hash for two arguments. Returns a string.
+Returns a string.
 
-### `computeHashOnElements(data: BigNumberish[])`
+### computeHashOnElements
 
-<br/>
+`computeHashOnElements(data: BigNumberish[])`
 
-Function to compute a Pedersen hash on a array of elements. Returns a string.
+Function to compute a Pedersen hash on a array of elements.
 
-<br/>
+Returns a string.
 
-### `calculateTransactionHashCommon(txHashPrefix: TransactionHashPrefix, version: BigNumberish,contractAddress: BigNumberish, entryPointSelector: BigNumberish, calldata: BigNumberish[], maxFee: BigNumberish, chainId: StarknetChainId, additionalData: BigNumberish[] = []): string`
+### calculateTransactionHashCommon
+
+`calculateTransactionHashCommon(txHashPrefix: TransactionHashPrefix, version: BigNumberish,contractAddress: BigNumberish, entryPointSelector: BigNumberish, calldata: BigNumberish[], maxFee: BigNumberish, chainId: StarknetChainId, additionalData: BigNumberish[] = []): string`
 
 Calculates the transaction hash in the StarkNet network - a unique identifier of the transaction.
 
 Called internally in `calculateDeployTransactionHash` and `calculcateTransactionHash`.
 
-<br/>
+### calculateDeployTransactionHash
 
-### `calculateDeployTransactionHash(contractAddress: BigNumberish, constructorCalldata: BigNumberish[], version: BigNumberish, chainId: StarknetChainId): string`
+`calculateDeployTransactionHash(contractAddress: BigNumberish, constructorCalldata: BigNumberish[], version: BigNumberish, chainId: StarknetChainId): string`
 
 Function that calculates the deployment transaction hash in the StarkNet network.
 
 Internally calls `calculateTransactionHashCommon` with `TransactionHashPrefix.DEPLOY`.
 
-<br/>
+### calculcateTransactionHash
 
-### `calculcateTransactionHash(contractAddress: BigNumberish, version: BigNumberish, entryPointSelector: BigNumberish, calldata: BigNumberish[], maxFee: BigNumberish, chainId: StarknetChainId): string`
+`calculcateTransactionHash(contractAddress: BigNumberish, version: BigNumberish, entryPointSelector: BigNumberish, calldata: BigNumberish[], maxFee: BigNumberish, chainId: StarknetChainId): string`
 
 Function that internally calls `calculateTransactionHashCommon`, with `TransactionHashPrefix.INVOKE`.
 
@@ -258,8 +279,64 @@ const hashMsg = calculcateTransactionHash(
 );
 ```
 
-<br/>
+### calculateContractAddressFromHash
+
+`calculateContractAddressFromHash(salt: BigNumberish, classHash: BigNumberish, constructorCalldata: RawCalldata, deployerAddress: BigNumberish)`
+
+Function that calculates contract address from hash.
+
+Returns a string.
+
+<hr />
+
+## **ellipticCurve**
+
+Wrapper around the javascript `elliptic` library with additional functionality.
+
+### genKeyPair
+
+`ec.genKeyPair()`
+
+Generate a random key pair.
+
+### getKeyPair
+
+`getKeyPair(pk: BigNumberish): KeyPair`
+
+Get a key pair from a private key.
+
+### getStarkKey
+
+`getStarkKey(keyPair: KeyPair): string`
+
+Public key defined over a Stark-friendly elliptic curve that is different from the standard Ethereum elliptic curve
+
+### getKeyPairFromPublicKey
+
+`getKeyPairFromPublicKey(publicKey: BigNumberish): KeyPair`
+
+Takes a public key and casts it into `elliptic` KeyPair format.
+
+Returns keyPair with public key only, which can be used to verify signatures, but can't sign anything.
+
+### sign
+
+`sign(keyPair: KeyPair, msgHash: string): Signature`
+
+Signs a message using the provided key.
+
+keyPair should be an KeyPair with a valid private key.
+
+Returns an Signature.
+
+### verify
+
+`verify(keyPair: KeyPair | KeyPair[], msgHash: string, sig: Signature): boolean`
+
+Verifies a message using the provided key.
+
+keyPair should be an KeyPair with a valid public key.
 
-### `calculateContractAddressFromHash(salt: BigNumberish, classHash: BigNumberish, constructorCalldata: RawCalldata, deployerAddress: BigNumberish)`
+sig should be an Signature.
 
-Function that calculates contract address from hash. Returns a string.
+Returns true if the verification succeeds.