starknet 4.3.0 → 4.4.1

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.
 
@@ -162,9 +176,15 @@ const signature = await this.signer.signTransaction(transactions, signerDetails)
 }
 ```
 
+### bigNumberishArrayToHexadecimalStringArray
+
+`bigNumberishArrayToHexadecimalStringArray(rawCalldata: BigNumberish[]): string[]`
+
+Convert BigNumberish array to hexadecimal string array. Used for signature conversion.
+
 <hr />
 
-## `uint256`
+## **uint256**
 
 ```js
 // Represents an integer in the range [0, 2^256).
@@ -176,74 +196,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 +285,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.

package/www/guides/account.md

@@ -43,9 +43,9 @@ const compiledAccount = json.parse(
 );
 ```
 
-> **Note** 
-> 
-> below example uses [Argent's](https://github.com/argentlabs/argent-contracts-starknet/blob/develop/contracts/ArgentAccount.cairo) account contract 
+> **Note**
+>
+> below example uses [Argent's](https://github.com/argentlabs/argent-contracts-starknet/blob/develop/contracts/ArgentAccount.cairo) account contract
 
 ```javascript
 const accountResponse = await defaultProvider.deployContract({
@@ -54,9 +54,9 @@ const accountResponse = await defaultProvider.deployContract({
 });
 ```
 
-> **Note** 
-> 
-> below example uses [OpenZeppelin's](https://github.com/OpenZeppelin/cairo-contracts/blob/main/src/openzeppelin/account/presets/Account.cairo) account contract 
+> **Note**
+>
+> below example uses [OpenZeppelin's](https://github.com/OpenZeppelin/cairo-contracts/blob/main/src/openzeppelin/account/presets/Account.cairo) account contract
 
 ```javascript
 const accountResponse = await defaultProvider.deployContract({
@@ -74,16 +74,16 @@ Wait for the deployment transaction to be accepted and assign the address of the
 await defaultProvider.waitForTransaction(accountResponse.transaction_hash);
 ```
 
-Once account contract is deployed [Account](../docs/API/account.md) instance can be created. Use your new account instance to sign transactions, messages or verify signatures! 
-
-> **Note**
-> 
-> Make sure your Account has enough funds to execute invocations. Use this [faucet](https://faucet.goerli.starknet.io/) for funding on testnet.
+Once account contract is deployed [Account](../docs/API/account.md) instance can be created. Use your new account instance to sign transactions, messages or verify signatures!
 
 ```js
 const account = new Account(
     defaultProvider,
-    accountResponse.address,
+    accountResponse.contract_address,
     starkKeyPair
 );
 ```
+
+## Fund your new account!
+
+Make sure your Account has enough funds to execute invocations. Use this [faucet](https://faucet.goerli.starknet.io/) for funding on testnet.

package/www/guides/erc20.md

@@ -20,26 +20,41 @@ await defaultProvider.waitForTransaction(erc20Response.transaction_hash);
 ## Get the erc20 contract address and create the contact object
 
 ```javascript
-const erc20Address = erc20Response.address;
-const erc20 = new Contract(compiledErc20.abi, erc20Address);
+const erc20Address = erc20Response.contract_address;
+const erc20 = new Contract(compiledErc20.abi, erc20Address, defaultProvider);
 ```
 
 ## Mint tokens to an account address
 
 Make sure you created the `Account` instance following the [Creating an Account](./account.md) guide.
 
+Also make sure you added funds to your account!
+
 ```javascript
 erc20.connect(account);
 
 const { transaction_hash: mintTxHash } = await erc20.mint(
   account.address,
-  "1000"
+  "1000",
+  {
+    maxFee: "1"
+  }
 );
 
 console.log(`Waiting for Tx to be Accepted on Starknet - Minting...`);
 await defaultProvider.waitForTransaction(mintTxHash);
 ```
 
+> **Note**
+>
+> Transaction can be rejected if `maxFee` is lower than actual.
+>
+> _Error: REJECTED: FEE_TRANSFER_FAILURE_
+>
+> _Actual fee exceeded max fee._
+>
+> If this occurs, set `maxFee` to a higher value, for example: 999999995330000
+
 ## Check balance after mint
 
 ```javascript
@@ -64,7 +79,7 @@ const { transaction_hash: transferTxHash } = await account.execute(
     calldata: [erc20Address, "10"],
   },
   undefined,
-  { maxFee: "0" }
+  { maxFee: "1" }
 );
 
 // Wait for the invoke transaction to be accepted on StarkNet

package/www/guides/intro.md

@@ -16,6 +16,8 @@ npm install starknet@next
 
 Please check the StarkNet documentation <ins>[here](https://www.cairo-lang.org/docs/hello_starknet/intro.html)</ins> to compile starknet contracts.
 
+Additional helpful resources can also be found at [OpenZeppelin](https://docs.openzeppelin.com/contracts-cairo/0.3.1/) documentation site.
+
 ## Full example with account & erc20
 
-Please see workshop <ins>[here](https://github.com/0xs34n/starknet.js-workshop)</ins>
+Please take a look at our workshop <ins>[here](https://github.com/0xs34n/starknet.js-workshop)</ins>.