starknet 4.13.2 → 4.14.0

package/src/utils/events.ts

@@ -0,0 +1,32 @@
+import { UDC } from '../constants';
+import { InvokeTransactionReceiptResponse } from '../types/provider';
+import { cleanHex } from './number';
+
+/**
+ * Parse Transaction Receipt Event from UDC invoke transaction and
+ * create DeployContractResponse compatibile response with adition of UDC Event data
+ *
+ * @param txReceipt
+ * @returns DeployContractResponse | UDC Event Response data
+ */
+export function parseUDCEvent(txReceipt: InvokeTransactionReceiptResponse) {
+  if (!txReceipt.events) {
+    throw new Error('UDC emited event is empty');
+  }
+  const event = txReceipt.events.find(
+    (it) => cleanHex(it.from_address) === cleanHex(UDC.ADDRESS)
+  ) || {
+    data: [],
+  };
+  return {
+    transaction_hash: txReceipt.transaction_hash,
+    contract_address: event.data[0],
+    address: event.data[0],
+    deployer: event.data[1],
+    unique: event.data[2],
+    classHash: event.data[3],
+    calldata_len: event.data[4],
+    calldata: event.data.slice(5, 5 + parseInt(event.data[4], 16)),
+    salt: event.data[event.data.length - 1],
+  };
+}

package/src/utils/number.ts

@@ -34,6 +34,12 @@ export function toFelt(num: BigNumberish): string {
   return toBN(num).toString();
 }
 
+/**
+ * Remove hex string leading zero and lower case '0x01A'.. -> '0x1a..'
+ * @param hex string
+ */
+export const cleanHex = (hex: string) => hex.toLowerCase().replace(/^(0x)0+/, '$1');
+
 /*
  Asserts input is equal to or greater then lowerBound and lower then upperBound.
  Assert message specifies inputName.

package/www/docs/API/account.md

@@ -6,7 +6,7 @@ sidebar_position: 2
 
 An Account extends <ins>[`Provider`](/docs/API/provider)</ins> and inherits all of its methods.
 
-It also introduces new methods that allow Accounts to create and verify signatures with a custom <ins>[`Signer`](/docs/API/signer)</ins>.
+It also introduces new methods that allow Accounts to create and verify signatures with a custom <ins>[`Signer`](/docs/API/signer)</ins>, declare and deploy Contract and deploy new Account
 
 This API is the primary way to interact with an account contract on StarkNet.
 
@@ -89,7 +89,7 @@ The _estimateFeeDetails_ object may include any of:
 
 account.**estimateAccountDeployFee**(contractPayload [ , estimateFeeDetails ]) => _Promise < EstimateFeeResponse >_
 
-Estimate Fee for executing a DEPLOY_ACCOUNT transaction on starknet
+Estimate Fee for executing a DEPLOY_ACCOUNT transaction on StarkNet
 
 The _contractPayload_ object structure:
 
@@ -142,6 +142,8 @@ The _transactionsDetail_ object may include any of:
 
 <hr />
 
+### Declare
+
 account.**declare**(contractPayload [ , transactionsDetail ]) => _Promise < DeclareContractResponse >_
 
 Declares a given compiled contract (json) to starknet.
@@ -180,6 +182,158 @@ const declareTx = await account.declare({
 
 <hr />
 
+### Deploy
+
+Deploys a given compiled contract (json) to starknet, wrapper around _execute_ invoke function
+
+**deploy**(deployContractPayload [ , transactionsDetail ]) => _Promise < InvokeFunctionResponse >_
+
+@param object **_deployContractPayload_**
+
+- **classHash**: computed class hash of compiled contract
+- **constructorCalldata**: constructor calldata
+- optional salt: address salt - default random
+- optional unique: bool if true ensure unique salt - default true
+- optional additionalCalls - optional additional calls array to support multi-call
+
+@param object **transactionsDetail** Invocation Details
+
+- optional nonce
+- optional version
+- optional maxFee
+
+@returns **transaction_hash**
+
+Example:
+
+```typescript
+  const deployment = await account.deploy({
+    classHash: erc20ClassHash,
+    constructorCalldata: [
+      encodeShortString('Token'),
+      encodeShortString('ERC20'),
+      account.address,
+    ],
+    salt: randomAddress(),
+    unique: true, // Using true here so as not to clash with normal erc20 deploy in account and provider test
+  });
+
+  await provider.waitForTransaction(deployment.transaction_hash);
+```
+
+Example multi-call:
+
+```typescript
+TODO Example with multi-call
+```
+
+<hr />
+
+### DeployContract
+
+✅ NEW
+High level wrapper for deploy. Doesn't require waitForTransaction. Response similar to deprecated provider deployContract.
+
+**deployContract**(payload [ , details ]) => _Promise < DeployContractUDCResponse >_
+
+@param object **_payload_** UniversalDeployerContractPayload
+
+- **classHash**: computed class hash of compiled contract
+- **constructorCalldata**: constructor calldata
+- optional salt: address salt - default random
+- optional unique: bool if true ensure unique salt - default true
+- optional additionalCalls - optional additional calls array to support multi-call
+
+@param object **details** InvocationsDetails
+
+- optional nonce
+- optional version
+- optional maxFee
+
+@returns Promise DeployContractUDCResponse
+
+- contract_address
+- transaction_hash
+- address
+- deployer
+- unique
+- classHash
+- calldata_len
+- calldata
+- salt
+
+Example:
+
+```typescript
+  const deployResponse = await account.deployContract({
+    classHash: erc20ClassHash,
+    constructorCalldata: [
+      encodeShortString('Token'),
+      encodeShortString('ERC20'),
+      account.address,
+    ],
+  });
+```
+
+<hr />
+
+### DeclareDeploy
+
+✅ NEW
+High level wrapper for declare & deploy. Doesn't require waitForTransaction. Functionality similar to deprecated provider deployContract. Declare and Deploy contract using single function.
+
+**declareDeploy**(payload [ , details ]) => _Promise < DeclareDeployContractResponse >_
+
+@param object **_payload_** DeclareDeployContractPayload
+
+- **contract**: compiled contract code
+- **classHash**: computed class hash of compiled contract
+- optional constructorCalldata: constructor calldata
+- optional salt: address salt - default random
+- optional unique: bool if true ensure unique salt - default true
+- optional additionalCalls - optional additional calls array to support multi-call
+
+@param object **details** InvocationsDetails
+
+- optional nonce
+- optional version
+- optional maxFee
+
+@returns Promise object DeclareDeployContractResponse
+
+- declare: CommonTransactionReceiptResponse
+  - transaction_hash
+- deploy: DeployContractUDCResponse;
+  - contract_address
+  - transaction_hash
+  - address
+  - deployer
+  - unique
+  - classHash
+  - calldata_len
+  - calldata
+  - salt
+  <hr />
+
+Example:
+
+```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;
+```
+
+### deployAccount
+
 account.**deployAccount**(contractPayload [ , transactionsDetail ]) => _Promise < DeployContractResponse >_
 
 Declares a given compiled contract (json) to starknet.

package/www/docs/API/contractFactory.md

@@ -8,33 +8,29 @@ Contract Factory allow you to deploy contracts to StarkNet. To deploy a Contract
 
 ## Creating an instance
 
-`new starknet.ContractFactory( compiledContract , providerOrAccount, [ , abi ] )`
+`new starknet.ContractFactory( compiledContract, classHash, account, [ , abi ] )`
 
 Creates a new instance of a ContractFactory for the contract described by the _compiledContract_.
 
-`contractFactory.connect(providerOrAccount)` _for changing the provider or account_
+`contractFactory.connect(account)` _for changing the provider or account_
 
 `contractFactory.attach(address)` _for changing the address of the connected contract factory_
 
 ## Properties
 
-contractFactory.**abi** => _Abi_
+contractFactory.**compiledContract** => _CompiledContract_ (the compiled contract the contractFactory was constructed with)
 
-The ABI the contractFactory was constructed with.
+contractFactory.**classHash** => _string_ (contract classHash can be obtained using tool for compiling contract)
 
-contractFactory.**compiledContract** => _CompiledContract_
+contractFactory.**account** => _AccountInterface_ (account that are used to interact with the network)
 
-The compiled contract the contractFactory was constructed with.
-
-contractFactory.**providerOrAccount** => _ProviderInterface | AccountInterface_
-
-Provider or account that are used to interact with the network.
+contractFactory.**abi** => _Abi_ (the ABI the contractFactory was constructed with)
 
 ## Methods
 
 contractFactory.**attach**( address ) ⇒ _Contract_
 
-Return an instance of a _Contract_ attached to address. This is the same as using the _Contract_ constructor with address and this _compiledContract_ and _providerOrAccount_ passed in when creating the ContractFactory.
+Return an instance of a _Contract_ attached to address. This is the same as using the _Contract_ constructor with address and this _compiledContract_ and _account_ passed in when creating the ContractFactory.
 
 <hr />
 

package/www/docs/API/provider.md

@@ -141,9 +141,9 @@ Estimate fee for invoke transaction.
 
 <hr/>
 
-provider.**getNonce**(contractAddress, blockIdentifier) => _Promise < BigNumberish >_
+provider.**getNonceForAddress**(contractAddress, blockIdentifier) => _Promise < BigNumberish >_
 
-Gets the nonce of the provided contractAddress.
+Gets the nonce of the provided contractAddress. This was renamed from `getNonce` to `getNonceForAddress` to avoid confusion when inheriting an Account from the Provider class.
 
 <hr/>
 
@@ -242,7 +242,9 @@ Estimate fee for declare transaction.
 
 <hr/>
 
-provider.**waitForTransaction**(txHash [ , retryInterval]) => _Promise < void >_
+### waitForTransaction
+
+provider.**waitForTransaction**(txHash [ , retryInterval]) => _Promise < GetTransactionReceiptResponse >_
 
 Wait for the transaction to be accepted on L2 or L1.
 
@@ -476,12 +478,6 @@ Gets the latest block number.
 
 <hr/>
 
-provider.**getNonce**(contractAddress, blockIdentifier) => _Promise < BigNumberish >_
-
-Gets the nonce of the provided contractAddress
-
-<hr/>
-
 provider.**getPendingTransactions**() => _Promise < PendingTransactions >_
 
 ###### _PendingTransactions_

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);
+```