diff --git a/content/sdk/00.index.md b/content/sdk/00.index.md index 9a41b40a..700cde22 100644 --- a/content/sdk/00.index.md +++ b/content/sdk/00.index.md @@ -74,7 +74,7 @@ Integrate ZKsync GO SDK for ZKsync Era features. --- title: Python icon: i-heroicons-circle-stack -to: /sdk/python/getting-started +to: /sdk/python/quickstart/getting-started --- Explore Nuxt built-in components for pages, layouts, head, and more. :: diff --git a/content/sdk/10.js/00.ethers/00.index.md b/content/sdk/10.js/00.ethers/00.index.md index 4cab821b..3ec36729 100644 --- a/content/sdk/10.js/00.ethers/00.index.md +++ b/content/sdk/10.js/00.ethers/00.index.md @@ -12,7 +12,7 @@ support common operations developers require and serve as an excellent starting There are two main versions of the zksync-ethers SDK: V5 and V6. Each version caters to different needs and provides distinct features and improvements. -::callout +::callout{icon="i-heroicons-light-bulb"} Check out the [installation guide](/sdk/js/ethers/installation-js) for installation instructions. :: diff --git a/content/sdk/10.js/00.ethers/01.why-zksync-ethers.md b/content/sdk/10.js/00.ethers/01.why-zksync-ethers.md index daa331fa..3187568e 100644 --- a/content/sdk/10.js/00.ethers/01.why-zksync-ethers.md +++ b/content/sdk/10.js/00.ethers/01.why-zksync-ethers.md @@ -36,7 +36,7 @@ features and improvements, ensuring compatibility with future advancements in ZK technologies. The SDK is regularly updated to incorporate the latest developments, providing developers with a powerful and flexible tool for building next-generation blockchain applications. -::callout +::callout{icon="i-heroicons-light-bulb"} Explore the [zksync-ethers documentation](/sdk/js/ethers) to get started and take advantage of all the features and benefits it offers. :: diff --git a/content/sdk/10.js/00.ethers/02.installation-js.md b/content/sdk/10.js/00.ethers/02.installation-js.md index 68313a29..59feb3ce 100644 --- a/content/sdk/10.js/00.ethers/02.installation-js.md +++ b/content/sdk/10.js/00.ethers/02.installation-js.md @@ -7,7 +7,7 @@ tags: ["zksync", "installation", "setup", "ethereum", "sdk"] Learn how to install and set up the `zksync-ethers` library to interact with the ZKsync network, leveraging its features for Ethereum scaling and Layer 2 solutions. -::callout +::callout{icon="i-heroicons-light-bulb"} If you're migrating from `zksync-web3`, please refer to the [migration guide](/sdk/js/ethers/v6/migration) for detailed instructions. :: diff --git a/content/sdk/10.js/00.ethers/03.compatibility-js.md b/content/sdk/10.js/00.ethers/03.compatibility-js.md new file mode 100644 index 00000000..14694a57 --- /dev/null +++ b/content/sdk/10.js/00.ethers/03.compatibility-js.md @@ -0,0 +1,31 @@ +--- +title: Platform Compatibility +description: Platforms compatible with zksync-ethers v5 and v6 +tags: ["compatibility", "ethers.js", "zksync"] +--- + +`zksync-ethers` supports all modern browsers (Chrome, Edge, Firefox, Safari, etc.) & runtime +environments (Node.js, React Native, Electron). + +## Ethers v5 compatibility + +- **Node.js**: v12.x and above. +- **Browser**: All modern browsers (Chrome, Firefox, Safari, Edge). +- **React Native**: Supported via `react-native-ethers`. +- **Electron**: Standard configurations supported. +- **TypeScript**: Included type definitions. + +## Ethers v6 compatibility + +- **Node.js**: v14.x and above +- **Browser**: Optimized for all modern browsers. +- **React Native**: Improved support via the latest `react-native-ethers`. +- **Electron**: Enhanced integration for desktop applications. +- **TypeScript**: Comprehensive type definitions for better developer experience. +- **BigInt**: Required for certain functionalities in ethers v6. + +Both versions offer robust platform compatibility, ensuring seamless integration with ZKsync across different environments. + +::callout{icon="i-heroicons-light-bulb"} +For more detailed information and specific configurations, refer to the [official zksync-ethers documentation](https://zksync.io/sdk/js/ethers). +:: diff --git a/content/sdk/30.python/00.getting-started.md b/content/sdk/30.python/00.getting-started.md deleted file mode 100644 index c99e3e82..00000000 --- a/content/sdk/30.python/00.getting-started.md +++ /dev/null @@ -1,65 +0,0 @@ ---- -title: Getting Started -description: ---- - -## Concept - -While most of the existing SDKs should work out of the box, deploying smart contracts or using unique ZKsync features, -like account abstraction, requires providing additional fields to those that Ethereum transactions have by default. - -To provide easy access to all the features of ZKsync Era, the `zksync2` Python SDK was created, which is made in a way -that has an interface very similar to those of [web3.py](https://web3py.readthedocs.io/en/latest/index.html). -In fact, `web3.py` is a peer dependency of our library and most of the objects exported by `zksync2` inherit -from the corresponding `web3.py` objects and override only the fields that need to be changed. - -## Prerequisites - -- Python: >=3.8 ([installation guide](https://www.python.org/downloads/)) -- Pip: 23.1.2 ([installation guide](https://pip.pypa.io/en/stable/installation/)) - -## Adding dependencies - -To install ZKsync Era, run the command below in your terminal. - -```shell -pip install zksync2 -``` - -## Connecting to ZKsync Era - -Once you have all the necessary dependencies, connect to ZKsync Era using the endpoint of the operator node. - -```python -from zksync2.module.module_builder import ZkSyncBuilder -... -sdk = ZkSyncBuilder.build("https://sepolia.era.zksync.dev") -``` - -Get chain id: - -```python -chain_id = zk_web3.zksync.chain_id -``` - -Get block number: - -```python -block_number = zk_web3.zksync.block_number -``` - -Get the transaction by hash: - -```ts -transaction = zksync_web3.zksync.eth_get_transaction_by_hash(hash); -``` - -Also, the following examples demonstrate how to: - -1. [Deposit ETH and tokens from Ethereum into ZKsync Era](https://github.com/zksync-sdk/zksync2-examples/blob/main/python/01_deposit.py) -2. [Transfer ETH and tokens on ZKsync Era](https://github.com/zksync-sdk/zksync2-examples/blob/main/python/02_transfer.py) -3. [Withdraw ETH and tokens from ZKsync Era to Ethereum](https://github.com/zksync-sdk/zksync2-examples/blob/main/python/09_withdrawal.py) -4. [Use paymaster to pay fee with token](https://github.com/zksync-sdk/zksync2-examples/blob/main/python/15_use_paymaster.py) - -Full code for all examples is available [here](https://github.com/zksync-sdk/zksync2-examples/tree/main/python). -Examples are configured to interact with `ZKsync Era` and `Sepolia` test networks. diff --git a/content/sdk/30.python/00.quickstart/00.getting-started.md b/content/sdk/30.python/00.quickstart/00.getting-started.md new file mode 100644 index 00000000..63c248e7 --- /dev/null +++ b/content/sdk/30.python/00.quickstart/00.getting-started.md @@ -0,0 +1,60 @@ +--- +title: Overview +description: An introduction to the ZKsync Python SDK and its features. +tags: ["zksync", "python", "sdk", "overview"] +--- + +## Concept + +Most existing SDKs work right away, but deploying smart contracts or using unique ZKsync features, like account +abstraction, needs extra fields that Ethereum transactions don't have by default. + +To make it easy to use all ZKsync Era features, we created the `zksync2` Python SDK. This SDK has an interface similar +to [web3.py](https://web3py.readthedocs.io/en/latest/index.html). In fact, `web3.py` is a peer dependency of our +library. Most objects exported by `zksync2` inherit from `web3.py` objects and only change the fields that need adjustments. + +::callout{icon="i-heroicons-light-bulb"} +Explore the [installation guide](https://github.com/zksync-sdk/zksync2-examples/tree/main/python) to get started with +the ZKsync Python SDK. +:: + +## Connecting to ZKsync Era + +Once you have all the necessary dependencies, connect to ZKsync Era using the operator node endpoint. + +```python +from zksync2.module.module_builder import ZkSyncBuilder + +sdk = ZkSyncBuilder.build("https://sepolia.era.zksync.dev") +``` + +Get the chain ID: + +```python +chain_id = zk_web3.zksync.chain_id +``` + +Get the block number: + +```python +block_number = zk_web3.zksync.block_number +``` + +Get the transaction by hash: + +```python +transaction = zk_web3.zksync.eth_get_transaction_by_hash(hash) +``` + +## Examples + +These examples show how to: + +1. [Deposit ETH and tokens from Ethereum into ZKsync Era](https://github.com/zksync-sdk/zksync2-examples/blob/main/python/01_deposit.py) +2. [Transfer ETH and tokens on ZKsync Era](https://github.com/zksync-sdk/zksync2-examples/blob/main/python/02_transfer.py) +3. [Withdraw ETH and tokens from ZKsync Era to Ethereum](https://github.com/zksync-sdk/zksync2-examples/blob/main/python/09_withdrawal.py) +4. [Use paymaster to pay fees with tokens](https://github.com/zksync-sdk/zksync2-examples/blob/main/python/15_use_paymaster.py) + +You can find the full code for all examples in +the [Python ZKsync SDK](https://github.com/zksync-sdk/zksync2-examples/tree/main/python). These examples are set up to +work with `ZKsync Era` and `Sepolia` test networks. diff --git a/content/sdk/30.python/00.quickstart/01.why-python-sdk.md b/content/sdk/30.python/00.quickstart/01.why-python-sdk.md new file mode 100644 index 00000000..04f394e4 --- /dev/null +++ b/content/sdk/30.python/00.quickstart/01.why-python-sdk.md @@ -0,0 +1,45 @@ +--- +title: Why Python SDK +description: Benefits and features of Python SDK for ZKsync Era. +tags: ["zksync", "ethers", "sdk", "python"] +--- + +### Easy integration + +The ZKsync Python SDK integrates seamlessly with your existing Python projects. Its interface is similar to the +popular [web3.py](https://web3py.readthedocs.io/en/latest/index.html) library, making it easy for developers +familiar with Ethereum development to get started quickly. + +### Comprehensive functionality + +The SDK gives you access to all the unique features of ZKsync Era, including: + +- **Account abstraction**: Deploy and manage smart contracts with extra fields that standard Ethereum transactions +don't have. +- **Optimized performance**: Benefit from ZKsync's scalability and speed improvements directly through the SDK. + +### Consistent API + +The SDK maintains a consistent API with `web3.py`, ensuring a smooth transition and reducing the learning curve. Most +objects exported by `zksync2` inherit from `web3.py` objects, with only necessary modifications. + +### Strong community support + +As part of the ZKsync ecosystem, the Python SDK benefits from strong [community support](https://join.zksync.dev/) +and regular updates. You can +find extensive documentation, examples, and a helpful community ready to assist you. + +### Security and reliability + +The ZKsync Python SDK is built with security and reliability in mind. It leverages ZKsync’s robust infrastructure to +ensure secure and reliable transactions and interactions with the blockchain. + +### Active development + +The SDK is actively developed and maintained by the ZKsync team. This ensures that you always have access to the +latest features and improvements, keeping your projects up to date with the evolving blockchain landscape. + +::callout{icon="i-heroicons-light-bulb"} +Explore the [Python SDK documentation](/sdk/python/quickstart/getting-started) to get started and take advantage of all the +features and benefits it offers. +:: diff --git a/content/sdk/30.python/00.quickstart/02.installation-python.md b/content/sdk/30.python/00.quickstart/02.installation-python.md new file mode 100644 index 00000000..215471fd --- /dev/null +++ b/content/sdk/30.python/00.quickstart/02.installation-python.md @@ -0,0 +1,41 @@ +--- +title: Installation +description: How to install and set up Python SDK for your project. +tags: ["zksync", "installation", "setup", "python", "sdk"] +--- + +## Prerequisites + +Make sure you have the following software installed on your system: + +- **Python**: Version 3.8 or higher. Download and install it from the [Python website](https://www.python.org/downloads/). +- **Pip**: Version 23.1.2 or higher. Pip is the package installer for Python. Install it using the guide on the [Pip website](https://pip.pypa.io/en/stable/installation/). + +## Adding dependencies + +To add the ZKsync Era SDK to your project, follow these steps: + +1. **Open your terminal**: Use any terminal or command line interface you like. + +2. **Install the ZKsync Era SDK**: Run this command to install the SDK with pip: + + ```shell + pip install zksync2 + ``` + +## Verification + +Check if the installation was successful by importing the SDK in a Python script or an interactive Python session: + +```python +import importlib.metadata + +zksync_version = importlib.metadata.version("zksync2") +print("ZKsync SDK version:", zksync_version) +``` + +You should see a response like: + +```sh +ZKsync SDK version: 1.2.0 +``` diff --git a/content/sdk/30.python/00.quickstart/03.platform-compatibility-python.md b/content/sdk/30.python/00.quickstart/03.platform-compatibility-python.md new file mode 100644 index 00000000..a9064a16 --- /dev/null +++ b/content/sdk/30.python/00.quickstart/03.platform-compatibility-python.md @@ -0,0 +1,37 @@ +--- +title: Platform Compatibility +description: Platforms compatible with Python SDK +tags: ["compatibility", "python", "zksync"] +--- + +The ZKsync Python SDK supports various platforms to ensure smooth integration and functionality. Here are the details: + +## Compatible platforms + +### Operating systems + +- **Windows**: Fully supported on Windows 10 and later versions. +- **macOS**: Fully supported on macOS 10.15 (Catalina) and later versions. +- **Linux**: Compatible with major distributions like Ubuntu, Debian, Fedora, and CentOS. + +### Python versions + +- **Python 3.8**: Supported +- **Python 3.9**: Supported +- **Python 3.10**: Supported +- **Python 3.11**: Supported + +### Development Environments + +- **IDEs**: Works well with popular Integrated Development Environments like PyCharm, VSCode, and Atom. +- **Virtual environments**: Compatible with virtual environment tools like `venv` and `virtualenv`. + +### Additional dependencies + +The SDK relies on certain dependencies to ensure full functionality. Make sure you have these installed: + +- **web3.py**: A peer dependency required by `zksync2`. + + ```shell + pip install web3 + ``` diff --git a/content/sdk/70.faq.md b/content/sdk/70.faq.md index 82bb34bc..10b6fdcb 100644 --- a/content/sdk/70.faq.md +++ b/content/sdk/70.faq.md @@ -17,16 +17,15 @@ ZKsync Era SDKs are toolkits designed to help developers build decentralized app Era network. They provide the necessary libraries and tools to interact with ZKsync. ### How do I get started with ZKsync Era SDKs? -You can start by visiting the official ZKsync documentation, which provides comprehensive guides, tutorials, and API -references to help you begin building dApps on ZKsync Era. +You can start by visiting the [official ZKsync documentation](/sdk), which provides comprehensive guides, tutorials, +and API references to help you begin building dApps on ZKsync Era. -### What types of dApps can be built using ZKsync Era SDKs? -ZKsync Era SDKs can be used to build a variety of dApps, including DeFi protocols, NFT marketplaces, gaming -applications, and more, leveraging Ethereum smart contract capabilities. +### How do I connect to ZKsync Era using the Python SDK? -### Can ZKsync Era be used for NFT applications? -Yes, ZKsync Era supports the ERC-721 standard, enabling the development of NFT applications on its platform. +To connect to ZKsync Era, use the operator node endpoint. Here is an example of how to set it up: -### How does ZKsync Era handle data availability? -ZKsync Era uses off-chain storage for most data, with periodic updates and validity proofs submitted to the Ethereum -mainnet to ensure data availability and security. +```python +from zksync2.module.module_builder import ZkSyncBuilder + +sdk = ZkSyncBuilder.build("https://sepolia.era.zksync.dev") +``` diff --git a/content/sdk/80.troubleshooting.md b/content/sdk/80.troubleshooting.md index 22c823a2..59b6f096 100644 --- a/content/sdk/80.troubleshooting.md +++ b/content/sdk/80.troubleshooting.md @@ -17,50 +17,74 @@ correct endpoint for the L2 network is: [ZKsync Sepolia Explorer](%%zk_testnet_b 2. **Transaction hash and block tag**: Use the correct transaction hash and block tag when fetching transaction details. -### Bun +### Python -If you encounter issues using Bun during the installation, refer to the troubleshooting steps in the table below. +1. **Unable to Install the ZKsync Python SDK** -##### 1. Network timeout + - Ensure you have Python 3.8 or higher installed. You can download the latest version from the [Python website](https://www.python.org/downloads/). + - Make sure you have pip version 23.1.2 or higher. You can upgrade pip by running: -- **Possible cause**: Slow or unstable internet connection -- **Solution**: Increase the timeout duration by using: `curl -fsSL --connect-timeout 60 https://bun.sh/install | bash` + ```shell + pip install --upgrade pip + ``` -##### 2. Manual download required + - Run the installation command: -- **Possible cause**: Automatic download fails -- **Solution**: Manually download the Bun binary from -the [Bun releases page on GitHub](https://github.com/oven-sh/bun/releases/latest). Extract the binary and place it in a -directory that is in your system's PATH. + ```shell + pip install zksync2 + ``` -##### 3. Permissions issue +2. **ImportError: No module named 'zksync2'** -- **Possible cause**: Bun binary is not executable -- **Solution**: Ensure the Bun binary is executable by running: `chmod +x ~/.bun/bin/bun` + - Verify the installation by running: -##### 4. PATH not updated + ```shell + pip show zksync2 + ``` -- **Possible cause**: `~/.bun/bin` not in PATH -- **Solution**: Verify and manually add it to your PATH by editing your shell configuration -file (`~/.zshrc` for zsh): `echo 'export PATH="$HOME/.bun/bin:$PATH"' >> ~/.zshrc && source ~/.zshrc` + :::callout + If it is not installed, follow the installation steps in number 1. + ::: + - Ensure your Python script is using the correct Python environment where `zksync2` is installed. -##### 5. TTY initialization failed +3. **Connection Error When Connecting to ZKsync Era** -- **Possible cause**: Terminal handling issues or TTY not supported -- **Solution**: Run without TTY by setting the environment variable: `NO_TTY=1 bun install` or disable -telemetry: `export NUXT_TELEMETRY_DISABLED=1` + - Check your internet connection. + - Ensure you are using the correct operator node endpoint. -##### 6. Telemetry prompt issue + ```python + from zksync2.module.module_builder import ZkSyncBuilder -- **Possible cause**: Nuxt telemetry prompt causing issues -- **Solution**: Set an environment variable to disable the telemetry prompt: `export NUXT_TELEMETRY_DISABLED=1` + sdk = ZkSyncBuilder.build("https://sepolia.era.zksync.dev") + ``` -##### 7. Conflicting aliases + - Verify the endpoint URL is correct and the service is operational. -- **Possible cause**: Conflicts with existing aliases or functions -- **Solution**: Ensure there are no conflicting aliases or functions named `bun` by running: `type bun` +4. **AttributeError: 'module' object has no attribute 'zksync'** -##### 8. Reinitialize shell + - Make sure you are using the correct import statements and setup: -- **Possible cause**: Shell environment not refreshed -- **Solution**: Completely reinitialize your shell environment by starting a new shell session: `exec /bin/zsh` + ```python + from zksync2.module.module_builder import ZkSyncBuilder + + sdk = ZkSyncBuilder.build("https://sepolia.era.zksync.dev") + ``` + + - Ensure you are accessing the attributes correctly. + + ```python + chain_id = sdk.zksync.chain_id + ``` + +5. **Transaction Rejection or Failure** + + - Verify that your transaction parameters are correct and meet all the required fields. + - Ensure your account has sufficient funds for the transaction. + - Check the gas limit and gas price to ensure they are set appropriately. + - Review any error messages returned by the transaction to identify specific issues. + +6. **Incorrect or Unexpected Response Data** + + - Double-check the method you are calling and the parameters you are passing. + - Ensure that you are handling the response data correctly in your script. + - Refer to the official documentation and examples to confirm correct usage of the SDK methods. diff --git a/content/sdk/90.glossary.md b/content/sdk/90.glossary.md index 28a8e82b..4e1fee82 100644 --- a/content/sdk/90.glossary.md +++ b/content/sdk/90.glossary.md @@ -7,30 +7,15 @@ navigation: false Familiarize yourself with important terminology to better understand the documentation and enhance your development process. -### ZKsync Era -ZKsync Era is a Layer 2 scaling solution for Ethereum, utilizing zk-rollup technology to enable scalable and low-cost -transactions while maintaining the security and trust of the Ethereum blockchain. - -### ZK-Rollup -A type of Layer 2 scaling solution that bundles multiple transactions into a single batch and generates a -cryptographic proof (known as a zero-knowledge proof) that is submitted to the Ethereum mainnet. This process increases -throughput and reduces fees. - -### Layer 2 (L2) -A secondary framework or protocol that is built on top of an existing blockchain system (Layer 1). Layer 2 solutions -aim to improve the scalability and efficiency of the underlying blockchain. +### Account abstraction +A feature that allows more complex logic in managing accounts and transactions, beyond the default capabilities of +Ethereum accounts. -### Layer 1 (L1) -The base layer or main blockchain architecture, such as the Ethereum mainnet, which handles all transaction -validations and security. - -### SDK (Software Development Kit) -A collection of software tools, libraries, documentation, and code samples that enable developers to create -applications for a specific platform. +### Block number +A sequential number indicating the position of a block within the blockchain. -### dApp (Decentralized Application) -An application that runs on a decentralized network, such as Ethereum, utilizing smart contracts to function without a -central authority. +### Endpoint +A specific URL where an API can be accessed by a client application. ### ERC-20 A widely-used standard for creating fungible tokens on the Ethereum blockchain. It ensures that tokens can be traded, @@ -44,25 +29,36 @@ can represent ownership of real-world items, digital art, collectibles, and more A multi-token standard that supports both fungible and non-fungible tokens within a single contract, offering more flexibility and efficiency in managing various types of assets. -### ZKsync Sepolia Explorer -A block explorer specifically for the ZKsync Era on the Sepolia testnet, providing detailed information about -transactions, blocks, and addresses on the network. +### Layer 1 (L1) +The base layer or main blockchain architecture, such as the Ethereum mainnet, which handles all transaction +validations and security. + +### Layer 2 (L2) +A secondary framework or protocol that is built on top of an existing blockchain system (Layer 1). Layer 2 solutions +aim to improve the scalability and efficiency of the underlying blockchain. + +### Paymaster +A mechanism in ZKsync that allows users to pay transaction fees with tokens instead of ETH. + +### Peer dependency +A library that a project depends on, which should be installed by the user, often because it is a shared dependency +between multiple projects. -### Bun -A fast JavaScript runtime and package manager compatible with Node.js packages, designed to improve the performance -and developer experience for building JavaScript applications. +### Transaction hash +A unique identifier assigned to each transaction processed on the blockchain. -### Ethers.js -A library for interacting with the Ethereum blockchain, providing a comprehensive and straightforward API for -developers to integrate Ethereum-based functionalities into their applications. +### web3.py +A Python library for interacting with Ethereum. It is often used for building decentralized applications (DApps). -### Telemetry -The process of collecting and transmitting data from remote or inaccessible points to an IT system in a different -location for monitoring and analysis. +### ZKsync Era +ZKsync Era is a Layer 2 scaling solution for Ethereum, utilizing zk-rollup technology to enable scalable and low-cost +transactions while maintaining the security and trust of the Ethereum blockchain. -### PATH -An environment variable in Unix-like operating systems and Windows, specifying a set of directories where executable -programs are located. +### ZK-Rollup +A type of Layer 2 scaling solution that bundles multiple transactions into a single batch and generates a +cryptographic proof (known as a zero-knowledge proof) that is submitted to the Ethereum mainnet. This process increases +throughput and reduces fees. -### Shell configuration file -A script file that initializes variables and settings for a shell session, such as `.bashrc` for Bash or `.zshrc` for Zsh. +### ZKsync sepolia explorer +A block explorer specifically for the ZKsync Era on the Sepolia testnet, providing detailed information about +transactions, blocks, and addresses on the network.