diff --git a/src/SUMMARY.md b/src/SUMMARY.md index 60f72bf51..bb0573cfd 100644 --- a/src/SUMMARY.md +++ b/src/SUMMARY.md @@ -15,21 +15,20 @@ - [Scarb: The Package Manager](ch02-03-scarb.md) - [Katana: A Local Node](ch02-04-katana.md) - [Testnet Deployment](ch02-05-testnet-deployment.md) - - [Starknet Devnet](ch02-06-starknet-devnet.md) - - [Foundry Cast: Interacting with Starknet](ch02-05-foundry-cast.md) - - [Example - Deployment Script](ch02-05-01-deployment-script.md) - - [Starknet-js: Javascript SDK](ch02-07-starknet-js.md) - - [Examples](ch02-07-01-examples.md) - - [Beginner - Counter UI](ch02-07-01-00-counter-ui.md) - - [Beginner - ERC-20 UI](ch02-07-01-01-erc20-ui.md) - - [Starknet-React: React Integration](ch02-08-starknet-react.md) - - [Examples](ch02-08-01-examples.md) - - [Beginner - ERC-20 UI](ch02-08-01-01-erc20-ui.md) - - [Intermediate - Million Dollar Homepage](ch02-08-01-02-million-dollar-homepage.md) - - [Starknet-py: Python SDK 🚧](ch02-09-starknet-py.md) - - [Starknet-rs: Rust SDK 🚧](ch02-10-starknet-rs.md) - - [Starkli: Querying the Blockchain 🚧](ch02-11-starkli.md) - - [Foundry Forge: Testing](ch02-12-foundry-forge.md) + - [Starkli: Querying Starknet](ch02-06-starkli.md) + - [Example - Beginner: Connection Script](ch02-06-01-connection-script.md) + - [Starknet Devnet](ch02-07-starknet-devnet.md) + - [Foundry Cast: Interacting with Starknet](ch02-08-foundry-cast.md) + - [Example - Intermediate: Deployment Script](ch02-08-01-deployment-script.md) + - [Starknet-js: Javascript SDK](ch02-09-starknet-js.md) + - [Example - Beginner: Counter UI](ch02-09-01-counter-ui.md) + - [Example - Beginner: ERC-20 UI](ch02-09-02-erc20-ui.md) + - [Starknet-React: React Integration](ch02-10-starknet-react.md) + - [Example - Beginner: ERC-20 UI](ch02-10-01-erc20-ui.md) + - [Example - Intermediate: Million Dollar Homepage](ch02-10-02-million-dollar-homepage.md) + - [Starknet-py: Python SDK 🚧](ch02-11-starknet-py.md) + - [Starknet-rs: Rust SDK 🚧](ch02-12-starknet-rs.md) + - [Foundry Forge: Testing](ch02-13-foundry-forge.md) ## Architecture diff --git a/src/ch02-11-01-connection-script.md b/src/ch02-06-01-connection-script.md similarity index 100% rename from src/ch02-11-01-connection-script.md rename to src/ch02-06-01-connection-script.md diff --git a/src/ch02-11-starkli.md b/src/ch02-06-starkli.md similarity index 100% rename from src/ch02-11-starkli.md rename to src/ch02-06-starkli.md diff --git a/src/ch02-07-01-examples.md b/src/ch02-07-01-examples.md deleted file mode 100644 index 6f58c9410..000000000 --- a/src/ch02-07-01-examples.md +++ /dev/null @@ -1,10 +0,0 @@ -# Examples - -In this subchapter, readers will find practical examples demonstrating the usage of `starknet-js`. It provides insight into real-world applications and serves as a guide for developers to understand and implement these tools effectively. - -We value the contribution of our developer community: - -- We encourage developers to contribute additional examples. -- Please inform us if you identify any mistakes or inaccuracies. - -Your insights and feedback are instrumental in making this resource more comprehensive and accurate. diff --git a/src/ch02-06-starknet-devnet.md b/src/ch02-07-starknet-devnet.md similarity index 100% rename from src/ch02-06-starknet-devnet.md rename to src/ch02-07-starknet-devnet.md diff --git a/src/ch02-05-01-deployment-script.md b/src/ch02-08-01-deployment-script.md similarity index 100% rename from src/ch02-05-01-deployment-script.md rename to src/ch02-08-01-deployment-script.md diff --git a/src/ch02-08-01-examples.md b/src/ch02-08-01-examples.md deleted file mode 100644 index f1363ab8a..000000000 --- a/src/ch02-08-01-examples.md +++ /dev/null @@ -1,10 +0,0 @@ -# Examples - -In this subchapter, readers will find practical examples demonstrating the usage of `starknet-react`. It provides insight into real-world applications and serves as a guide for developers to understand and implement these tools effectively. - -We value the contribution of our developer community: - -- We encourage developers to contribute additional examples. -- Please inform us if you identify any mistakes or inaccuracies. - -Your insights and feedback are instrumental in making this resource more comprehensive and accurate. diff --git a/src/ch02-05-foundry-cast.md b/src/ch02-08-foundry-cast.md similarity index 100% rename from src/ch02-05-foundry-cast.md rename to src/ch02-08-foundry-cast.md diff --git a/src/ch02-07-01-00-counter-ui.md b/src/ch02-09-01-counter-ui.md similarity index 100% rename from src/ch02-07-01-00-counter-ui.md rename to src/ch02-09-01-counter-ui.md diff --git a/src/ch02-07-01-01-erc20-ui.md b/src/ch02-09-02-erc20-ui.md similarity index 100% rename from src/ch02-07-01-01-erc20-ui.md rename to src/ch02-09-02-erc20-ui.md diff --git a/src/ch02-07-starknet-js.md b/src/ch02-09-starknet-js.md similarity index 100% rename from src/ch02-07-starknet-js.md rename to src/ch02-09-starknet-js.md diff --git a/src/ch02-08-01-01-erc20-ui.md b/src/ch02-10-01-erc20-ui.md similarity index 100% rename from src/ch02-08-01-01-erc20-ui.md rename to src/ch02-10-01-erc20-ui.md diff --git a/src/ch02-08-01-02-million-dollar-homepage.md b/src/ch02-10-02-million-dollar-homepage.md similarity index 100% rename from src/ch02-08-01-02-million-dollar-homepage.md rename to src/ch02-10-02-million-dollar-homepage.md diff --git a/src/ch02-08-starknet-react.md b/src/ch02-10-starknet-react.md similarity index 100% rename from src/ch02-08-starknet-react.md rename to src/ch02-10-starknet-react.md diff --git a/src/ch02-11-foundry-forge.md b/src/ch02-11-foundry-forge.md deleted file mode 100644 index 71f9196aa..000000000 --- a/src/ch02-11-foundry-forge.md +++ /dev/null @@ -1,211 +0,0 @@ -# Foundry Forge: Testing 🚧 - -[Starknet Foundry](https://github.com/foundry-rs/starknet-foundry) is a tool designed for testing and developing Starknet contracts. It is an adaptation of the Ethereum Foundry for Starknet, aiming to expedite the development process. - -The project consists of two primary components: - -- **Forge**: A testing tool specifically for Cairo contracts. This tool acts as a test runner and boasts features designed to enhance your testing process. Tests are written directly in Cairo, eliminating the need for other programming languages. Additionally, the Forge implementation uses Rust, mirroring Ethereum Foundry's choice of language. -- **Cast**: This serves as a DevOps tool for Starknet, initially supporting a series of commands to interface with Starknet. In the future, Cast aims to offer deployment scripts for contracts and other DevOps functions. - -## Forge - -Merely deploying contracts is not the end game. Many tools have offered this capability in the past. Forge sets itself apart by hosting a Cairo VM instance, enabling the sequential execution of tests. It employs Scarb for contract compilation. - -To utilize Forge, define test functions and label them with test attributes. Users can either test standalone Cairo functions or integrate contracts, dispatchers, and test contract interactions on-chain. - -## `snForge` Command-Line Usage - -This section guides you through the Starknet Foundry `snforge` command-line tool. Learn how to set up a new project, compile the code, and execute tests. - -To start a new project with Starknet Foundry, use the `--init` command and replace `project_name` with your project's name. - -```shell -snforge --init project_name -``` - -Once you've set up the project, inspect its layout: - -```shell -cd project_name -tree . -L 1 -``` - -The project structure is as follows: - -```shell -. -├── README.md -├── Scarb.toml -├── src -└── tests -``` - -- `src/` holds your contract source code. -- `tests/` is the location of your test files. -- `Scarb.toml` is for project and **`snforge`** configurations. - -Ensure the casm code generation is active in the `Scarb.toml` file: - -```shell -# ... -[[target.starknet-contract]] -casm = true -# ... -``` - -To run tests using `snforge`: - -```shell -snforge - -Collected 2 test(s) from the `test_name` package -Running 0 test(s) from `src/` -Running 2 test(s) from `tests/` -[PASS] tests::test_contract::test_increase_balance -[PASS] tests::test_contract::test_cannot_increase_balance_with_zero_value -Tests: 2 passed, 0 failed, 0 skipped -``` - -## Integrating `snforge` with Existing Scarb Projects - -For those with an established Scarb project who wish to incorporate `snforge`, ensure the `snforge_std package` is declared as a dependency. Insert the line below in the [dependencies] section of your `Scarb.toml`: - -```shell -# ... -[dependencies] -snforge_std = { git = "https://github.com/foundry-rs/starknet-foundry.git", tag = "[VERSION]" } -``` - -Ensure the tag version corresponds with your `snforge` version. To verify your `snforge` version: - -```sh -snforge --version -``` - -Or, add this dependency using the `scarb` command: - -```shell -scarb add snforge_std --git https://github.com/foundry-rs/starknet-foundry.git --tag VERSION -``` - -With these steps, your existing Scarb project is now **`snforge`**-ready. - -## Testing with `snforge` - -Utilize Starknet Foundry's `snforge` command to efficiently run tests. - -### Executing Tests - -Navigate to the package directory and issue this command to run tests: - -```shell -snforge -``` - -Sample output might resemble: - -```shell -Collected 3 test(s) from `package_name` package -Running 3 test(s) from `src/` -[PASS] package_name::executing -[PASS] package_name::calling -[PASS] package_name::calling_another -Tests: 3 passed, 0 failed, 0 skipped -``` - -### Filter Tests - -Run specific tests using a filter string after the `snforge` command. Tests matching the filter based on their absolute module tree path will be executed: - -```shell -$ snforge calling -``` - -### Run a Specific Test - -Use the `--exact` flag and a fully qualified test name to run a particular test: - -```shell -snforge package_name::calling --exact -``` - -### Stop After First Test Failure - -To stop after the first test failure, add the `--exit-first` flag to the `snforge` command: - -```shell -snforge --exit-first -``` - -## Basic Example - -The example provided below demonstrates how to test a Starknet contract using `snforge`. - -```rust -#[starknet::interface] -trait IHelloStarknet { - fn increase_balance(ref self: TContractState, amount: felt252); - fn get_balance(self: @TContractState) -> felt252; -} - -#[starknet::contract] -mod HelloStarknet { - #[storage] - struct Storage { - balance: felt252, - } - - #[external(v0)] - impl HelloStarknetImpl of super::IHelloStarknet { - // Increases the balance by the specified amount. - fn increase_balance(ref self: ContractState, amount: felt252) { - self.balance.write(self.balance.read() + amount); - } - - // Returns the balance. - fn get_balance(self: @ContractState) -> felt252 { - self.balance.read() - } - } -} -``` - -Remember, the identifier following `mod` signifies the contract name. Here, the contract name is `HelloStarknet`. - -### Craft the Test - -Below is a test for the **`HelloStarknet`** contract. This test deploys **`HelloStarknet`** and interacts with its functions: - -```rust -use snforge_std::{ declare, ContractClassTrait }; - -#[test] -fn call_and_invoke() { - // Declare and deploy the contract - let contract = declare('HelloStarknet'); - let contract_address = contract.deploy(@ArrayTrait::new()).unwrap(); - - // Instantiate a Dispatcher object for contract interactions - let dispatcher = IHelloStarknetDispatcher { contract_address }; - - // Invoke a contract's view function - let balance = dispatcher.get_balance(); - assert(balance == 0, 'balance == 0'); - - // Invoke another function to modify the storage state - dispatcher.increase_balance(100); - - // Validate the transaction's effect - let balance = dispatcher.get_balance(); - assert(balance == 100, 'balance == 100'); -} -``` - -To run the test, execute the `snforge` command. The expected output is: - -```shell -Collected 1 test(s) from using_dispatchers package -Running 1 test(s) from src/ -[PASS] using_dispatchers::call_and_invoke -Tests: 1 passed, 0 failed, 0 skipped -``` diff --git a/src/ch02-09-starknet-py.md b/src/ch02-11-starknet-py.md similarity index 100% rename from src/ch02-09-starknet-py.md rename to src/ch02-11-starknet-py.md diff --git a/src/ch02-10-starknet-rs.md b/src/ch02-12-starknet-rs.md similarity index 100% rename from src/ch02-10-starknet-rs.md rename to src/ch02-12-starknet-rs.md diff --git a/src/ch02-12-foundry-forge.md b/src/ch02-13-foundry-forge.md similarity index 100% rename from src/ch02-12-foundry-forge.md rename to src/ch02-13-foundry-forge.md diff --git a/src/sierra-not-push.md b/src/sierra-not-push.md deleted file mode 100644 index aaf401a1d..000000000 --- a/src/sierra-not-push.md +++ /dev/null @@ -1,147 +0,0 @@ -A Sierra compiled file has four key sections: - -- The Sierra Program: The program that will be executed on Starknet. -- The Contract Class Version: The version of the contract class that will be used. -- The Entry Points: The functions that can be called from outside the contract. -- The ABI: The interface that can be used to call the contract from outside Starknet. - -## ABI - -The smart contract ABI (Application Binary Interface) is an essential component that permits various software entities to communicate effectively with one another. Analogous to a restaurant menu that describes dishes in detail, the ABI provides a comprehensive blueprint of a smart contract's functions and events. With the example ABI in hand, let's delve deeper into its specifics. - -### **1. Implementation (`impl`):** - -- **Name**: OwnableImpl -- **Interface Name**: starknetpy::OwnableTrait - - This suggests that the OwnableImpl implementation derives or adheres to the "starknetpy::OwnableTrait" interface. - -### **2. Interface:** - -- **Name**: starknetpy::OwnableTrait -- **Items**: - - **Function 1**: - - **Name**: transfer_ownership - - **Inputs**: - - **Name**: new_owner - - **Type**: core::starknet::contract_address::ContractAddress - - This function allows for the contract's ownership to be transferred to another entity. As a parameter, it takes in the address of the new owner. - - **Outputs**: None - - **State Mutability**: external - - This means this function can be called externally and may alter the state of the contract. - - **Function 2**: - - **Name**: get_owner - - **Inputs**: None - - **Outputs**: - - **Type**: core::starknet::contract_address::ContractAddress - - The function, when invoked, returns the current owner's address. - - **State Mutability**: view - - This means the function doesn't alter the state of the contract and is mainly used for retrieving information. - -### **3. Constructor:** - -- **Name**: constructor -- **Inputs**: - - **Name**: init_owner - - **Type**: core::starknet::contract_address::ContractAddress - - The constructor is employed when deploying the contract. It sets the initial owner of the contract using the **`init_owner`** address parameter. - -### **4. Events:** - -- **Event 1**: - - **Name**: starknetpy::OwnableContract::OwnershipTransferred1 - - **Kind**: struct - - **Members**: - - **Member 1**: - - **Name**: prev_owner - - **Type**: core::starknet::contract_address::ContractAddress - - **Kind**: key - - **Member 2**: - - **Name**: new_owner - - **Type**: core::starknet::contract_address::ContractAddress - - **Kind**: key - - This event records ownership changes, detailing the previous and the new owner. -- **Event 2**: - - **Name**: starknetpy::OwnableContract::Event - - **Kind**: enum - - **Variants**: - - **Variant 1**: - - **Name**: OwnershipTransferred1 - - **Type**: starknetpy::OwnableContract::OwnershipTransferred1 - - **Kind**: nested - - This event mirrors the "OwnershipTransferred1" event. It is presented in an enumerable form, indicating that there might be other events added to this category in the future. - -From the deep dive into the ABI, it becomes evident that it is a robust descriptor of the smart contract's capabilities, outlining every function, event, and constructor in precise detail. Armed with this ABI, developers and other parties can effortlessly interface with the contract, fully comprehending its potential functionalities. - -[ -{ -"type": "impl", -"name": "OwnableImpl", -"interface_name": "starknetpy::OwnableTrait", -}, -{ -"type": "interface", -"name": "starknetpy::OwnableTrait", -"items": [ -{ -"type": "function", -"name": "transfer_ownership", -"inputs": [ -{ -"name": "new_owner", -"type": "core::starknet::contract_address::ContractAddress", -} -], -"outputs": [], -"state_mutability": "external", -}, -{ -"type": "function", -"name": "get_owner", -"inputs": [], -"outputs": [ -{"type": "core::starknet::contract_address::ContractAddress"} -], -"state_mutability": "view", -}, -], -}, -{ -"type": "constructor", -"name": "constructor", -"inputs": [ -{ -"name": "init_owner", -"type": "core::starknet::contract_address::ContractAddress", -} -], -}, -{ -"type": "event", -"name": "starknetpy::OwnableContract::OwnershipTransferred1", -"kind": "struct", -"members": [ -{ -"name": "prev_owner", -"type": "core::starknet::contract_address::ContractAddress", -"kind": "key", -}, -{ -"name": "new_owner", -"type": "core::starknet::contract_address::ContractAddress", -"kind": "key", -}, -], -}, -{ -"type": "event", -"name": "starknetpy::OwnableContract::Event", -"kind": "enum", -"variants": [ -{ -"name": "OwnershipTransferred1", -"type": "starknetpy::OwnableContract::OwnershipTransferred1", -"kind": "nested", -} -], -}, -]