starknet 4.13.2 → 4.15.0

package/www/docs/API/utils.md

@@ -136,6 +136,14 @@ Converts BN to hex.
 
 Returns a string.
 
+### cleanHex
+
+`cleanHex(hex: string): string`
+
+Remove leading zeroes and lowercase hex string after '0x'
+
+`0x01AFF` -> `0x1aff`
+
 ### hexToDecimalString
 
 `hexToDecimalString(hex: string): string`

package/www/guides/account.md

@@ -8,9 +8,22 @@ Since there are no Externally Owned Accounts (EOA) in StarkNet, all Accounts in
 
 Unlike in Ethereum where a wallet is created with a public and private key pair, StarkNet Accounts are the only way to sign transactions and messages, and verify signatures. Therefore a Account - Contract interface is needed.
 
-## Install and import StarkNet
+> Account contracts on StarkNet cannot be deployed without paying a fee.
 
-Install the latest version of starknet with `npm install starknet@next`
+High level explanations from StarkWare can be found in this Notion [page](https://starkware.notion.site/Deploy-a-contract-and-an-account-on-StarkNet-ed2fd13301d2414e8223bb72bb90e386), but in short, the process is:
+
+1. Decide on your account type (OpenZeppelin, Argent, ...)
+2. Compute the address of our would-be account off-chain (adressess on StarkNet are deterministic)
+3. Send funds to this pre-computed address. The funds will be used to pay for the account contract deployment
+4. Actual deployment of the Account
+
+## Install and setup
+
+Install the latest version of starknet with
+
+`npm install starknet@next`
+
+Imports example:
 
 ```javascript
 import fs from "fs";
@@ -21,69 +34,107 @@ import {
   ec,
   json,
   number,
+  hash
 } from "starknet";
 ```
 
-## Generate random key pair.
+Starknet.js currently doesn't have the functionality to calculate the class hash needed for the account deployment, so we need to calculate it with some other tool, for example: [Starkli](https://github.com/xJonathanLEI/starkli)
+
+```javascript
+// class hash of OpenZeppelin Account contract version 0.5.1
+const OZContractClassHash = '0x058d97f7d76e78f44905cc30cb65b91ea49a4b908a76703c54197bca90f81773';
+```
+
+```javascript
+// get the compiled contract ABI, in this case OpenZeppelin
+const compiledOZAccount = json.parse(
+  fs.readFileSync("./Account.json").toString("ascii")
+);
+```
 
-You can also get a key pair from a private key using `getKeyPair(pk: BigNumberish)`
+## Generate random key pair
 
 ```javascript
 const starkKeyPair = ec.genKeyPair();
 const starkKeyPub = ec.getStarkKey(starkKeyPair);
 ```
 
-## Deploy Account Contract
+You can also get a key pair from a private key using:
 
-Deploy the Account contract and wait for it to be verified on StarkNet.
+`getKeyPair(pk: BigNumberish)`
 
 ```javascript
-const compiledAccount = json.parse(
-  fs.readFileSync("./Account.json").toString("ascii")
-);
+const privateKey = '0x-Some-Existing-Private-Key'; // you can use stark.randomAddress();
+const starkKeyPair = ec.getKeyPair(privateKey);
+const starkKeyPub = ec.getStarkKey(starkKeyPair);
 ```
 
-> **Note**
->
-> below example uses [Argent's](https://github.com/argentlabs/argent-contracts-starknet/blob/develop/contracts/account/ArgentAccount.cairo) account contract
+## Pre-compute address of the Account
 
 ```javascript
-const accountResponse = await defaultProvider.deployContract({
-  contract: compiledAccount,
-  addressSalt: starkKeyPub,
-});
+const precalculatedAddress = hash.calculateContractAddressFromHash(
+    starkKeyPub, // salt
+    OZContractClassHash,
+    [starkKeyPub],
+    0
+  );
 ```
 
-> **Note**
->
-> below example uses [OpenZeppelin's](https://github.com/OpenZeppelin/cairo-contracts/blob/main/src/openzeppelin/account/presets/Account.cairo) account contract
+## Funding options for the pre-computed address
 
-```javascript
-const accountResponse = await defaultProvider.deployContract({
-    contract: compiledAccount,
-    constructorCalldata: [starkKeyPub],
-    addressSalt: starkKeyPub,
-});
+1. TESTNET
+
+You can do so by using a faucet: https://faucet.goerli.starknet.io/
+
+2. DEVNET
+
+Address is the newly `precalculatedAddress`.
+
+```bash
+curl -X POST http://127.0.0.1:5050/mint -d '{"address":"0x04a093c37ab61065d001550089b1089922212c60b34e662bb14f2f91faee2979","amount":50000000000000000000,"lite":true}' -H "Content-Type:application/json"
+// {"new_balance":50000000000000000000,"tx_hash":null,"unit":"wei"}
 ```
 
-## Use your new account
+3. Send funds from an already existing account
 
-Wait for the deployment transaction to be accepted and assign the address of the deployed account to the Account object.
+## OPTIONAL - Declare Account
+
+> NOTE: This step will fail if you haven't sent funds to the pre-calculated address.
+
+We need to use an already deployed account in order to declare ours. StarkNet will always have at least 1 already declared/deployed account for this purpose.
 
 ```javascript
-await defaultProvider.waitForTransaction(accountResponse.transaction_hash);
-```
+// In this case we will use the devnet's predeployed OZ account, after you start the devnet with: `starknet-devnet --seed 0`
+const devnetPrivateKey = '0xe3e70682c2094cac629f6fbed82c07cd';
+const devnetAccount0Address = '0x7e00d496e324876bbc8531f2d9a82bf154d1a04a50218ee74cdd372f75a551a';
+const devnetKeyPair = ec.getKeyPair(devnetPrivateKey);
 
-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!
+const predeployedAccount = new Account(provider, devnetAccount0Address, devnetKeyPair);
 
-```js
-const account = new Account(
-    defaultProvider,
-    accountResponse.contract_address,
-    starkKeyPair
-);
+const declareTx = await predeployedAccount.declare({
+  classHash: OZContractClassHash,
+  contract: compiledOZAccount
+});
+
+await provider.waitForTransaction(declareTx.transaction_hash);
 ```
 
-## Fund your new account!
+## Deploy Account Contract
+
+Deploy the Account contract and wait for it to be verified on StarkNet.
+
+> NOTE: This step will fail if you haven't sent funds to the pre-calculated address.
 
-Make sure your Account has enough funds to execute invocations. Use this [faucet](https://faucet.goerli.starknet.io/) for funding on testnet.
+```javascript
+const account = new Account(provider, precalculatedAddress, starkKeyPair);
+
+// This is OpenZeppelin account contract deployment
+const accountResponse = await account.deployAccount({
+  classHash: OZContractClassHash,
+  constructorCalldata: [starkKeyPub],
+  contractAddress: precalculatedAddress,
+  addressSalt: starkKeyPub
+});
+
+await provider.waitForTransaction(accountResponse.transaction_hash);
+```

package/www/guides/erc20.md

@@ -4,104 +4,160 @@ sidebar_position: 3
 
 # Deploy an ERC20 Contract
 
-Deploy the contract and wait for deployment transaction to be accepted on StarkNet
+Deploying a contract relies on having an account already set up with enough ETH to pay fees for both:
+
+1. The class declaration
+2. The transaction interacting with the UDC (universal deployer contract)
+
+> You must first declare your contract class and only then deploy a new instance of it!
+
+High level explanations from StarkWare can be found in this Notion [page](https://starkware.notion.site/Deploy-a-contract-and-an-account-on-StarkNet-ed2fd13301d2414e8223bb72bb90e386).
+
+ERC20 implementations:
+
+1. Argent ERC20 contract can be found [here](https://github.com/argentlabs/argent-contracts-starknet/blob/develop/contracts/lib/ERC20.cairo).
+2. OpenZeppelin ERC20 can be found [here](https://github.com/OpenZeppelin/cairo-contracts/tree/main/src/openzeppelin/token/erc20).
+
+## Setup
 
 ```javascript
 const compiledErc20 = json.parse(
   fs.readFileSync("./ERC20.json").toString("ascii")
 );
-const erc20Response = await defaultProvider.deployContract({
+```
+
+```javascript
+// devnet private key from Account #0 if generated with --seed 0
+const starkKeyPair = ec.getKeyPair("0xe3e70682c2094cac629f6fbed82c07cd");
+const accountAddress = "0x7e00d496e324876bbc8531f2d9a82bf154d1a04a50218ee74cdd372f75a551a";
+
+const recieverAddress = '0x69b49c2cc8b16e80e86bfc5b0614a59aa8c9b601569c7b80dde04d3f3151b79';
+
+// Starknet.js currently doesn't have the functionality to calculate the class hash
+const erc20ClassHash = '0x03f794a28472089a1a99b7969fc51cd5fbe22dd09e3f38d2bd6fa109cb3f4ecf';
+
+const account = new Account(
+    provider,
+    accountAddress,
+    starkKeyPair
+  );
+```
+
+## Declare contract
+
+```javascript
+const erc20DeclareResponse = await account.declare({
+  classHash: erc20ClassHash,
   contract: compiledErc20,
-  constructorCalldata: [encodeShortString('TokenName'), encodeShortString('TokenSymbol'), recipient], // Here the `recipient` receives the initial 1000 tokens
 });
 
-console.log("Waiting for Tx to be Accepted on Starknet - ERC20 Deployment...");
-await defaultProvider.waitForTransaction(erc20Response.transaction_hash);
+await provider.waitForTransaction(erc20DeclareResponse.transaction_hash);
 ```
 
-> **Note**
->
-> The ERC20 contract can be found [here](https://github.com/argentlabs/argent-contracts-starknet/blob/develop/contracts/lib/ERC20.cairo)
-
-## Get the erc20 contract address and create the contact object
+## Deploy contract
 
 ```javascript
-const erc20Address = erc20Response.contract_address;
-const erc20 = new Contract(compiledErc20.abi, erc20Address, defaultProvider);
+const salt = '900080545022'; // use some random salt
+
+const erc20Response = await account.deploy({
+  classHash: erc20ClassHash,
+  constructorCalldata: stark.compileCalldata({
+    name: shortString.encodeShortString('TestToken'),
+    symbol: shortString.encodeShortString('ERC20'),
+    decimals: 18,
+    initial_supply: ['1000'],
+    recipient: account.address,
+  }),
+  salt,
+});
+
+await provider.waitForTransaction(erc20Response.transaction_hash);
+
+const txReceipt = await provider.getTransactionReceipt(erc20Response.transaction_hash);
 ```
 
-## Mint tokens to an account address
+## Interact with contracts
 
-Make sure you created the `Account` instance following the [Creating an Account](./account.md) guide.
+We have 2 options to interact with contracts.
 
-Also make sure you added funds to your account!
+### Option 1 - call the contract object
 
 ```javascript
+const erc20 = new Contract(compiledErc20.abi, erc20Address, provider);
+
 erc20.connect(account);
 
-const { transaction_hash: mintTxHash } = await erc20.mint(
-  account.address,
- [ "1000", "0"]
+const { transaction_hash: mintTxHash } = await erc20.transfer(
+  recieverAddress,
+  ['0', '10'], // send 10 tokens as Uint256
+);
+
+await provider.waitForTransaction(mintTxHash);
+```
+
+### Option 2 - call contract from Account
+
+```javascript
+const executeHash = await account.execute(
   {
-    maxFee: "1"
+    contractAddress: erc20Address,
+    entrypoint: 'transfer',
+    calldata: stark.compileCalldata({
+      recipient: recieverAddress,
+      amount: ['10']
+    })
   }
 );
 
-console.log(`Waiting for Tx to be Accepted on Starknet - Minting...`);
-await defaultProvider.waitForTransaction(mintTxHash);
+await provider.waitForTransaction(executeHash.transaction_hash);
 ```
 
-> **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
+## Check the balance
 
 ```javascript
-console.log(`Calling StarkNet for account balance...`);
 const balanceBeforeTransfer = await erc20.balanceOf(account.address);
 
 console.log(
   `account Address ${account.address} has a balance of:`,
-  number.toBN(balanceBeforeTransfer.balance.low, 16).toString()
+  number.toBN(balanceBeforeTransfer[0].high).toString()
 );
 ```
 
-## Transfer tokens
+## Convenience Methods
 
-```javascript
-// Execute tx transfer of 10 tokens
-console.log(`Invoke Tx - Transfer 10 tokens back to erc20 contract...`);
-const { transaction_hash: transferTxHash } = await account.execute(
-  {
-    contractAddress: erc20Address,
-    entrypoint: "transfer",
-    calldata: [erc20Address, "10", "0"],
-  },
-  undefined,
-  { maxFee: "1" }
-);
+### deployContract convenience method
+
+High level wrapper for deploy. Doesn't require `waitForTransaction`. Response similar to deprecated `provider.deployContract`.
+
+Convenient also to get the address of the deployed contract in the same response - easier than using the `deploy` already mentioned in the guide.
 
-// Wait for the invoke transaction to be accepted on StarkNet
-console.log(`Waiting for Tx to be Accepted on Starknet - Transfer...`);
-await defaultProvider.waitForTransaction(transferTxHash);
+```typescript
+  const deployResponse = await account.deployContract({
+    classHash: erc20ClassHash,
+    constructorCalldata: [
+      encodeShortString('Token'),
+      encodeShortString('ERC20'),
+      account.address,
+    ],
+  });
 ```
 
-## Check balance after transfer
+### declareDeploy convenience method
 
-```javascript
-// Check balance after transfer - should be 1990 (1000 initial supply + 1000 mint - 10 transfer)
-console.log(`Calling StarkNet for account balance...`);
-const balanceAfterTransfer = await erc20.balanceOf(account.address);
+High level wrapper for declare & deploy. Doesn't require `waitForTransaction`. Functionality similar to deprecated `provider.deployContract`.
 
-console.log(
-  `account Address ${account.address} has a balance of:`,
-  number.toBN(balanceAfterTransfer.balance.low, 16).toString()
-);
+Declare and Deploy contract using single function:
+
+```typescript
+  const declareDeploy = await account.declareDeploy({
+    contract: compiledErc20,
+    classHash: '0x54328a1075b8820eb43caf0caa233923148c983742402dcfc38541dd843d01a',
+    constructorCalldata: [
+      encodeShortString('Token'),
+      encodeShortString('ERC20'),
+      account.address,
+    ],
+  });
+  const declareTransactionHash = declareDeploy.declare.transaction_hash
+  const erc20Address = declareDeploy.deploy.contract_address;
 ```

package/www/guides/intro.md

@@ -5,9 +5,12 @@ sidebar_position: 1
 # Getting Started
 
 ```bash
+
+# use the main branch
+
 npm install starknet
 
-# to use latest features
+# to use latest features (merges in develop branch)
 
 npm install starknet@next
 ```
@@ -16,8 +19,12 @@ 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.
+Additional helpful resources can also be found at <ins>[OpenZeppelin](https://docs.openzeppelin.com/contracts-cairo/0.5.0/)</ins> documentation site.
+
+Get the class hash of a contract: [starkli](https://github.com/xJonathanLEI/starkli).
+
+## Full example with account & erc20 deployments
 
-## Full example with account & erc20
+Please take a look at our workshop using OpenZeppelin contracts <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>.
+Example with Argent contract <ins>[here](https://github.com/0xs34n/starknet.js-account)</ins>.