From d1989961783be64f93f30ce9b95d1e5ba65830f0 Mon Sep 17 00:00:00 2001 From: David Lehuby Date: Fri, 31 May 2024 14:31:49 +1000 Subject: [PATCH 01/12] Update Post HF Version + Landing page --- docs/berkeley-upgrade/appendix.mdx | 82 --- .../archive-migration/appendix.mdx | 137 ---- .../archive-migration-installation.mdx | 151 ----- .../archive-migration-prerequisites.mdx | 66 -- .../archive-migration/debian-example.mdx | 79 --- .../archive-migration/docker-example.mdx | 75 --- .../archive-migration/index.mdx | 48 -- .../mainnet-database-maintenance.mdx | 196 ------ ...migrating-archive-database-to-berkeley.mdx | 632 ------------------ .../understanding-archive-migration.mdx | 56 -- docs/berkeley-upgrade/upgrade-steps.mdx | 132 ---- .../rosetta/run-with-docker.mdx | 2 +- docs/mina-protocol/sending-a-payment.mdx | 8 +- docs/node-developers/sandbox-node.mdx | 2 +- .../archive-node/getting-started.mdx | 18 +- .../connecting-to-the-network.mdx | 4 +- .../block-producer-node/getting-started.mdx | 4 +- .../flags-configs.mdx | 14 +- docs/node-operators/generating-a-keypair.mdx | 6 +- docs/node-operators/mina-signer.mdx | 71 ++ .../requirements.mdx | 0 .../seed-peers/getting-started.mdx | 2 +- docs/welcome.mdx | 25 +- docusaurus.config.js | 4 - sidebars.js | 31 +- src/components/features/HomepageFeatures.tsx | 2 +- 26 files changed, 110 insertions(+), 1737 deletions(-) delete mode 100644 docs/berkeley-upgrade/appendix.mdx delete mode 100644 docs/berkeley-upgrade/archive-migration/appendix.mdx delete mode 100644 docs/berkeley-upgrade/archive-migration/archive-migration-installation.mdx delete mode 100644 docs/berkeley-upgrade/archive-migration/archive-migration-prerequisites.mdx delete mode 100644 docs/berkeley-upgrade/archive-migration/debian-example.mdx delete mode 100644 docs/berkeley-upgrade/archive-migration/docker-example.mdx delete mode 100644 docs/berkeley-upgrade/archive-migration/index.mdx delete mode 100644 docs/berkeley-upgrade/archive-migration/mainnet-database-maintenance.mdx delete mode 100644 docs/berkeley-upgrade/archive-migration/migrating-archive-database-to-berkeley.mdx delete mode 100644 docs/berkeley-upgrade/archive-migration/understanding-archive-migration.mdx delete mode 100644 docs/berkeley-upgrade/upgrade-steps.mdx rename docs/{berkeley-upgrade => node-operators}/flags-configs.mdx (92%) rename docs/{berkeley-upgrade => node-operators}/requirements.mdx (100%) diff --git a/docs/berkeley-upgrade/appendix.mdx b/docs/berkeley-upgrade/appendix.mdx deleted file mode 100644 index 5e26fd33b..000000000 --- a/docs/berkeley-upgrade/appendix.mdx +++ /dev/null @@ -1,82 +0,0 @@ ---- -title: Appendix -sidebar_label: Appendix -hide_title: true -description: Berkeley Upgrade Appendix -keywords: - - Berkeley - - upgrade - - appendix ---- - -# Appendix - -## Migration from o1labs/client-sdk to mina-signer - -The signing library `o1labs/client-sdk` was deprecated some time ago and will stop working after the Mina mainnet upgrade. All users should upgrade to use the [mina-signer](https://www.npmjs.com/package/mina-signer) library. - -Below you will find an example of how to use the `mina-signer` library. Please keep in mind the following: - -1. Make sure to adjust the `nonce` to the correct nonce on the account you want to use as "sender" -1. Update the `url` variable with an existing Mina Node GraphQL endpoint - -```javascript -import { Client } from 'mina-signer'; - -// create the client and define the keypair - -const client = new Client({ network: 'testnet' }); // Mind the `network` client configuration option - -const senderPrivateKey = 'EKFd1Gx...'; // Sender's private key -const senderPublicKey = 'B62qrDM...'; // Sender's public key, perhaps derived from the private key using `client.derivePublicKey(senderPrivateKey)`; - -// define and sign payment - -let payment = { - from: senderPublicKey, - to: 'B62qkBw...', // Recipient public key - amount: 100, - nonce: 1, - fee: 1000000, -}; - -const signedPayment = client.signPayment(payment, senderPrivateKey); - -// send payment to graphql endpoint - -const url = 'https://qanet.minaprotocol.network/graphql'; - -const sendPaymentMutationQuery = ` -mutation SendPayment($input: SendPaymentInput!, $signature: SignatureInput!) { - sendPayment(input: $input, signature: $signature) { - payment { - hash - } - } -} -`; -const graphQlVariables = { - input: signedPayment.data, - signature: signedPayment.signature, -}; -const body = JSON.stringify({ - query: sendPaymentMutationQuery, - variables: graphQlVariables, - operationName: 'SendPayment', -}); - -const paymentResponse = await fetch(url, { - method: 'POST', - headers: { 'Content-Type': 'application/json' }, - body -}); - -const paymentResponseJson = await paymentResponse.json(); -if (paymentResponse.ok) { - console.log(`Transaction hash: ${paymentResponseJson.data.sendPayment.payment.hash}`); -} else { - console.error(JSON.stringify(paymentResponseJson)); -} - - -``` diff --git a/docs/berkeley-upgrade/archive-migration/appendix.mdx b/docs/berkeley-upgrade/archive-migration/appendix.mdx deleted file mode 100644 index 53525c8cf..000000000 --- a/docs/berkeley-upgrade/archive-migration/appendix.mdx +++ /dev/null @@ -1,137 +0,0 @@ ---- -title: Appendix -sidebar_label: Appendix -hide_title: true -description: archive node schema changes between Mainnet and Berkeley -keywords: - - Berkeley - - upgrade - - archive migration - - appendix - - mina archive node - - archive node ---- - -# Appendix - -## Archive node schema changes - -If you are using the Archive Node database directly for your system integrations, then you should understand all the changes that might impact your applications. The most important change is that the `balances` table in the Berkeley schema will no longer exist. In the new schema, it is replaced with the table `accounts_accessed` - from an application semantics point of view, the data in `accounts_accessed` is still the same. - -In the Berkeley protocol, accounts can now have the same public key but a different token_id. This means accounts are identified by both their public key and token_id, not just the public key. Consequently, the foreign key for the account in all tables is account_identifier_id instead of public_key_id. - -### Schema differences -- **Removed Types** - - The options `create_token`, `create_account`, and `mint_tokens` have been removed from the user_command_type enumeration. -- Indexes Dropped - - We've removed several indexes from tables, this may affect how you search and organize data: - - `idx_public_keys_id` - - `idx_public_keys_value` - - `idx_snarked_ledger_hashes_value` - - `idx_blocks_id` - - `idx_blocks_state_hash` -- **Table Removed** - - The `balances` table is no longer available. -- **New Tables Added** - - We've introduced the following new tables: - - `tokens` - - `token_symbols` - - `account_identifiers` - - `voting_for` - - `protocol_versions` - - `accounts_accessed` - - `accounts_created` - - `zkapp_commands` - - `blocks_zkapp_commands` - - `zkapp_field` - - `zkapp_field_array` - - `zkapp_states_nullable` - - `zkapp_states` - - `zkapp_action_states` - - `zkapp_events` - - `zkapp_verification_key_hashes` - - `zkapp_verification_keys` - - `zkapp_permissions` - - `zkapp_timing_info` - - `zkapp_uris` - - `zkapp_updates` - - `zkapp_balance_bounds` - - `zkapp_nonce_bounds` - - `zkapp_account_precondition` - - `zkapp_accounts` - - `zkapp_token_id_bounds` - - `zkapp_length_bounds` - - `zkapp_amount_bounds` - - `zkapp_global_slot_bounds` - - `zkapp_epoch_ledger` - - `zkapp_epoch_data` - - `zkapp_network_precondition` - - `zkapp_fee_payer_body` - - `zkapp_account_update_body` - - `zkapp_account_update` - - `zkapp_account_update_failures` -- **Updated Tables** - - The following tables have been updated - - `timing_info` - - `user_commands` - - `internal_commands` - - `epoch_data` - - `blocks` - - `blocks_user_commands` - - `blocks_internal_commands` - -### Differences per table -- **`timing_info`** - - Removed columns: - - `token` - - `initial_balance` -- **`user_commands`** - - Removed columns: - - `fee_token` - - `token` -- **`internal_commands`** - - Removed columns: - - `token` - - Renamed column - - `command_type` to `type` -- **`epoch_data`** - - Added columns: - - `total_currency` - - `start_checkpoint` - - `lock_checkpoint` - - `epoch_length` -- **`blocks`** - - Added columns: - - `last_vrf_output` - - `min_window_density` - - `sub_window_densities` - - `total_currency` - - `global_slot_since_hard_fork` - - `global_slot_since_genesis` - - `protocol_version_id` - - `proposed_protocol_version_id` - - Removed column: - - `global_slot` -- **`blocks_user_commands`** - - Removed columns: - - `fee_payer_account_creation_fee_paid` - - `receiver_account_creation_fee_paid` - - `created_token` - - `fee_payer_balance` - - `source_balance` - - `receiver_balance` - - Added index: - - `idx_blocks_user_commands_sequence_no` -- **`blocks_internal_commands`** - - Removed columns: - - `receiver_account_creation_fee_paid` - - `receiver_balance` - - Added indexes: - - `idx_blocks_internal_commands_sequence_no` - - `idx_blocks_internal_commands_secondary_sequence_no` - -### Rosetta API new operations - -The Berkeley upgrade introduces two new operation types: -- `zkapp_fee_payer_dec` -- `zkapp_balance_change` diff --git a/docs/berkeley-upgrade/archive-migration/archive-migration-installation.mdx b/docs/berkeley-upgrade/archive-migration/archive-migration-installation.mdx deleted file mode 100644 index 0a9398a87..000000000 --- a/docs/berkeley-upgrade/archive-migration/archive-migration-installation.mdx +++ /dev/null @@ -1,151 +0,0 @@ ---- -title: Installing the archive migration package -sidebar_label: Installing archive migration package -hide_title: false -description: Satisfying the archive migration prerequisites. -keywords: - - Berkeley - - upgrade - - archive migration - - installing - - prerequisites - - mina archive node - - archive node ---- - -The archive node Berkeley migration package is sufficient for satisfying the migration from Devnet/Mainnet to Berkeley. -However, it has some limitations. For example, the migration package does not migrate a non-canonical chain and it skips orphaned blocks that are not part of a canonical chain. - -To mitigate these limitations, the archive node maintenance package is available for use by archive node operators who want to maintain a copy of their Devnet and Mainnet databases for historical reasons. - -## Install with Google Cloud SDK - -The Google Cloud SDK installer does not always register a `google-cloud-sdk` apt package. The best way to install gsutil is using the apt repostory: - -```sh -curl https://packages.cloud.google.com/apt/doc/apt-key.gpg | sudo gpg --dearmor -o /usr/share/keyrings/cloud.google.gpg -echo "deb [signed-by=/usr/share/keyrings/cloud.google.gpg] https://packages.cloud.google.com/apt cloud-sdk main" | sudo tee -a /etc/apt/sources.list.d/google-cloud-sdk.list -sudo apt-get update && sudo apt-get install google-cloud-sdk -``` - -## Download the o1labs Mainnet archive database - -We strongly encourage you to perform the migration on your own data to preserve the benefits of decentralization. However, if you want to use the archive data that o1labs runs (for example, to bootstrap a new archive from SQL without waiting all day for the chain to download and replay), you can use the following steps: - -1. Download the Devnet/Mainnet archive data using cURL or gsutil: - - - cURL: - - For Devnet: - ```sh - curl https://storage.googleapis.com/mina-archive-dumps/devnet-archive-dump-{date}_0000.sql.tar.gz - ``` - - For Mainnet: - ```sh - curl https://storage.googleapis.com/mina-archive-dumps/mainnet-archive-dump-{date}_0000.sql.tar.gz - ``` - - To filter the dumps by date, replace `{date}` using the required `yyyy-dd-mm` format. For example, for March 15, 2024, use `2024-03-15`. - - :warning: The majority of backups have the `0000` suffix. If a download with that name suffix is not available, try incrementing it. For example, `0001`, `0002`, and so on. - - - gsutil: - - ```sh - gsutil cp gs://mina-archive-dumps/mainnet-archive-dump-2024-01-15* . - ``` - -2. Extract the tar package. - - ```sh - tar -xvzf {network}-archive-dump-{date}_0000.sql.tar.gz {network}-archive-dump-{date}_0000.sql - ``` - -3. Import the Devnet/Mainnet archive dump into the Berkeley database. - - Run this command at the database server: - - ```sh - psql -U {user} -f {network}-archive-dump-{date}_0000.sql - ``` - - The database in the dump **archive_balances_migrated** is created with the Devnet/Mainnet archive schema. - - Note: This database does not have any Berkeley changes. - -## Ensure the location of Google Cloud bucket with the Devnet/Mainnet precomputed blocks - -The recommended method is to perform migration on your own data to preserve the benefits of decentralization. - -`gsutil cp gs://mina_network_block_data/{network}-*.json .` - -:warning: Precomputed blocks for the Mainnet network take ~800 GB of disk space. Plan for adequate time to download these blocks. The Berkeley migration app downloads them incrementally only when needed. - -## Validate the Devnet/Mainnet database - -The correct Devnet/Mainnet database state is crucial for a successful migration. - -[Missing blocks](/berkeley-upgrade/archive-migration/mainnet-database-maintenance#missing-blocks) is one the most frequent issues when dealing with the Devnet/Mainnet archive. Although this step is optional, it is strongly recommended that you verify the archive condition before you start the migration process. - -To learn how to maintain archive data, see [Devnet/Mainnet database maintenance](/berkeley-upgrade/archive-migration/mainnet-database-maintenance). - -## Download the migration applications - -Migration applications are distributed as part of the archive migration Docker and Debian packages. - -Choose the packages that are appropriate for your environment. - -### Debian packages - -To get the Debian packages: - -``` -CODENAME=bullseye -CHANNEL=stable -VERSION=3.0.1-e848ecb - -echo "deb [trusted=yes] http://packages.o1test.net $CODENAME $CHANNEL" | tee /etc/apt/sources.list.d/mina.list -apt-get update -apt-get install --allow-downgrades -y "mina-archive-migration=$VERSION" -``` - -### Docker image - -To get the Docker image: - -``` -docker pull gcr.io/o1labs-192920/mina-archive-migration:3.0.1-e848ecb-{codename} -``` - -Where supported codenames are: -- bullseye -- focal -- buster - - -## Devnet/Mainnet genesis ledger - -The Mina Devnet/Mainnet genesis ledger is stored in GitHub in the `mina` repository under the `genesis_ledgers` subfolder. However, if you are already running a daemon that is connected to the Mina Mainnet or the Devnet network, you already have the genesis ledger locally. - -## Berkeley database schema files - -You can get the Berkeley schema files from different locations: - -- GitHub repository from the `berkeley` branch. - - Note: The `berkeley` branch can contain new updates regarding schema files, so always get the latest schema files instead of using an already downloaded schema. - -- Archive/Rosetta Docker from `berkeley` version - -### Example: Downloading schema sources from GitHub - - ```sh - wget https://raw.githubusercontent.com/MinaProtocol/mina/berkeley/src/app/archive/zkapp_tables.sql - - wget https://raw.githubusercontent.com/MinaProtocol/mina/berkeley/src/app/archive/create_schema.sql - ``` - -## Next steps - -Congratulations on completing the essential preparation and verification steps. You are now ready to perform the migration steps in [Migrating Devnet/Mainnet Archive to Berkeley Archive](/berkeley-upgrade/archive-migration/migrating-archive-database-to-berkeley). diff --git a/docs/berkeley-upgrade/archive-migration/archive-migration-prerequisites.mdx b/docs/berkeley-upgrade/archive-migration/archive-migration-prerequisites.mdx deleted file mode 100644 index 82c4cd68b..000000000 --- a/docs/berkeley-upgrade/archive-migration/archive-migration-prerequisites.mdx +++ /dev/null @@ -1,66 +0,0 @@ ---- -title: Archive migration prerequisites -sidebar_label: Archive migration prerequisites -hide_title: false -description: Overview of the migration tools and requirements to successfully migrate the Devnet/Mainnet archive database. -keywords: - - Berkeley - - upgrade - - archive migration - - planning - - prerequisites - - mina archive node - - archive node ---- - -To successfully migrate the archive database into the Berkeley version of the Mina network, you must ensure that your environment meets the foundational requirements. - -## Migration host - -- PostgreSQL database for database server -- If you use Docker, then any of the supported OS by Mina (bullseye, focal, or buster) with at least 32 GB of RAM -- gsutil application from Google Cloud Suite in version 5 or later -- (Optional) Docker in version 23.0 or later - -## (Optional) Devnet/Mainnet database - -One of the most obvious prerequisites is a Mainnet database. - -If you don't have an existing database with Devnet/Mainnet archive data, you can always download it from the Google Cloud bucket. However, we strongly encourage you to perform migration on your own data to preserve the benefits of decentralization. -You can use any gsutil-compatible alternative to Google Cloud or a gsutil wrapper program. - -## (Optional) Google Cloud bucket with Devnet/Mainnet precomputed blocks - -Precomputed blocks are the JSON files that a correctly configured node updloads to the Google Cloud bucket. -The Devnet/Mainnet to Berkeley archive data migration requires access to precomputed blocks that are uploaded by daemons that are connected to the Devnet or Mainnet networks. - -The **berkeley-migration** app uses the gsutil app to download blocks. If you didn't store precomputed blocks during the first phase of migration, you can use the precomputed blocks provided by Mina Foundation. -However, it is strongly recommended that you perform migration on your own data to preserve the benefits of decentralization. - -For Devnet blocks: - -```sh -gsutil cp gs://mina_network_block_data/devnet-*.json . -``` - -For Mainnet blocks: - -```sh -gsutil cp gs://mina_network_block_data/mainnet-*.json . -``` - -:warning: Precomputed blocks for the Mainnet network take ~800 GB of disk space. Plan for adequate time to download these blocks. The Berkeley migration app downloads them incrementally only when needed. You can instead download a 100 GB bundle of only the canonical Mainnet blocks that unpacks into ~220 GB: - -```sh -gsutil cp gs://mina_network_block_data/mainnet-bundle-2024-03-20.tar.zst . ; tar -xf mainnet-bundle-2024-03-20.tar.zst -``` - -:warning: Precomputed blocks for the Devnet network take several hundred GBs. Plan for adequate time to download these blocks. Instead, you can download a ~50 GB bundle of only the canonical Devnet blocks that unpacks into ~90 GB: - -```sh -gsutil cp gs://mina_network_block_data/devnet-bundle-3NKRsRWBzmPR8Z8ZmJb4u8FLpnSkjRitUpKZzVkHp11QuwP5i839.tar.gz . ; tar -xf devnet-bundle-3NKRsRWBzmPR8Z8ZmJb4u8FLpnSkjRitUpKZzVkHp11QuwP5i839.tar.gz -``` - -These bundles are partial. Updated documentation with the new links and final data will be provided _after_ the Berkeley major upgrade is completed. - -The best practice is to collect precomputed blocks by yourself or by other third parties to preserve the benefits of decentralization. diff --git a/docs/berkeley-upgrade/archive-migration/debian-example.mdx b/docs/berkeley-upgrade/archive-migration/debian-example.mdx deleted file mode 100644 index 7a76cc0a5..000000000 --- a/docs/berkeley-upgrade/archive-migration/debian-example.mdx +++ /dev/null @@ -1,79 +0,0 @@ ---- -title: Example of Devnet Archive Migration (Debian) -sidebar_label: Debian example (Devnet) -hide_title: true -description: A copy-paste example of how to do a Devnet migration. -keywords: - - Berkeley - - upgrade - - archive migration - - mina archive node - - archive node ---- - -# Debian example - -You can follow these steps that can be copy-pasted directly into a fresh Debian 11. - -This example uses an altered two-step version of the [full simplified workflow](/berkeley-upgrade/archive-migration/migrating-archive-database-to-berkeley#simplified-approach). - -```sh -apt update && apt install lsb-release sudo postgresql curl wget gpg # debian:11 is surprisingly light - -curl https://packages.cloud.google.com/apt/doc/apt-key.gpg | sudo gpg --dearmor -o /usr/share/keyrings/cloud.google.gpg -echo "deb [signed-by=/usr/share/keyrings/cloud.google.gpg] https://packages.cloud.google.com/apt cloud-sdk main" | sudo tee -a /etc/apt/sources.list.d/google-cloud-sdk.list -sudo apt-get update && sudo apt-get install google-cloud-sdk - -sudo rm /etc/apt/sources.list.d/mina*.list -sudo echo "deb [trusted=yes] http://packages.o1test.net $(lsb_release -cs) unstable" | sudo tee /etc/apt/sources.list.d/mina.list -sudo apt-get update && sudo apt-get install --allow-downgrades -y mina-archive-migration=3.0.0-rc1-4277e73 - -mkdir -p mina-migration-workdir -cd mina-migration-workdir - -gsutil cp gs://mina_network_block_data/devnet-bundle-3NKRsRWBzmPR8Z8ZmJb4u8FLpnSkjRitUpKZzVkHp11QuwP5i839.tar.gz . -tar -xf devnet-bundle-3NKRsRWBzmPR8Z8ZmJb4u8FLpnSkjRitUpKZzVkHp11QuwP5i839.tar.gz - -wget https://raw.githubusercontent.com/MinaProtocol/mina/berkeley/src/app/archive/create_schema.sql -wget https://raw.githubusercontent.com/MinaProtocol/mina/berkeley/src/app/archive/zkapp_tables.sql - -# this next step is required only if you don't have an archive yet -createdb devnet_balances_migrated -createdb devnet_really_migrated - -psql -d devnet_really_migrated -f create_schema.sql - -gsutil cp gs://mina-archive-dumps/devnet-archive-dump-2024-03-22_0000.sql.tar.gz . -tar -xf devnet-archive-dump-2024-03-22_0000.sql.tar.gz -# the next step ensures you don't accidentally merge mainnet and devnet data -sed -i -e s/archive_balances_migrated/devnet_balances_migrated/g devnet-archive-dump-2024-03-22_0000.sql -psql -d devnet_balances_migrated -f devnet-archive-dump-2024-03-22_0000.sql - -mina-berkeley-migration-script initial \ - --genesis-ledger /var/lib/coda/devnet.json \ - --source-db postgres:///devnet_balances_migrated \ - --target-db postgres:///devnet_really_migrated \ - --blocks-batch-size 100 --blocks-bucket mina_network_block_data \ - --network devnet - -# now, do a final migration - -gsutil cp gs://mina-archive-dumps/devnet-archive-dump-2024-03-22_2050.sql.tar.gz . -tar -xf devnet-archive-dump-2024-03-22_2050.sql.tar.gz -# the next step ensures you don't accidentally merge mainnet and devnet data -sed -i -e s/archive_balances_migrated/devnet_balances_migrated/g devnet-archive-dump-2024-03-22_2050.sql -psql -d devnet_balances_migrated -f devnet-archive-dump-2024-03-22_2050.sql - -curl -O https://gist.githubusercontent.com/ghost-not-in-the-shell/cfe629a15702e7bae7b0c1415fe0d85e/raw/8d8bff2814c1d0c15deb70b388dea8a28a485184/genesis.json - -mina-berkeley-migration-script final \ - --genesis-ledger /var/lib/coda/devnet.json \ - --source-db postgres:///devnet_balances_migrated \ - --target-db postgres:///devnet_really_migrated \ - --blocks-batch-size 100 --blocks-bucket mina_network_block_data \ - --network devnet \ - --replayer-checkpoint migration-checkpoint-437195.json \ - --fork-state-hash 3NKoUJX87VrfmNAoUdqoWUykVvt66ztm5rzruDQR7ihwYaWsdJKq \ - --fork-config genesis.json \ - --prefetch-blocks -``` diff --git a/docs/berkeley-upgrade/archive-migration/docker-example.mdx b/docs/berkeley-upgrade/archive-migration/docker-example.mdx deleted file mode 100644 index 372010248..000000000 --- a/docs/berkeley-upgrade/archive-migration/docker-example.mdx +++ /dev/null @@ -1,75 +0,0 @@ ---- -title: Example of Mainnet Archive Migration (Docker) -sidebar_label: Docker example (Mainnet) -hide_title: true -description: A copy-paste example of how to do a Mainnet migration. -keywords: - - Berkeley - - upgrade - - archive migration - - mina archive node - - archive node ---- - -# Docker example - -You can follow these steps that can be copy-pasted directly into a OS running Docker. - -This example performs a Mainnet initial migration following the [debian-example](/berkeley-upgrade/archive-migration/debian-example) - -```sh - -# Create a new directory for the migration data -mkdir $(pwd)/mainnet-migration && cd $(pwd)/mainnet-migration - -# Create Network -docker network create mainnet - -# Launch Local Postgres Database -docker run --name postgres -d -p 5432:5432 --network mainnet -v $(pwd)/mainnet-migration/postgresql/data:/var/lib/postgresql/data -e POSTGRES_USER=mina -e POSTGRES_PASSWORD=minamina -d postgres:13-bullseye - -export PGHOST="localhost" -export PGPORT=5432 -export PGUSER="mina" -export PGPASSWORD="minamina" - -# Drop DBs if they exist -psql -c "DROP DATABASE IF EXISTS mainnet_balances_migrated;" -psql -c "DROP DATABASE IF EXISTS mainnet_really_migrated;" - -# Create DBs -psql -c "CREATE DATABASE mainnet_balances_migrated;" -psql -c "CREATE DATABASE mainnet_really_migrated;" - -# Retrieve Archive Node Backup -wget https://673156464838-mina-archive-node-backups.s3.us-west-2.amazonaws.com/mainnet/mainnet-archive-dump-2024-04-29_0000.sql.tar.gz -tar -xf mainnet-archive-dump-2024-04-29_0000.sql.tar.gz - -# Replace the database name in the dump -sed -i -e s/archive_balances_migrated/mainnet_balances_migrated/g mainnet-archive-dump-2024-04-29_0000.sql -psql mainnet_balances_migrated -f mainnet-archive-dump-2024-04-29_0000.sql - -# Prepare target -wget https://raw.githubusercontent.com/MinaProtocol/mina/berkeley/src/app/archive/create_schema.sql -wget https://raw.githubusercontent.com/MinaProtocol/mina/berkeley/src/app/archive/zkapp_tables.sql -psql mainnet_really_migrated -f create_schema.sql - -# Start migration -docker create --name mainnet-db-migration \ - -v $(pwd)/mainnet-migration:/data \ - --network mainnet gcr.io/o1labs-192920/mina-archive-migration:3.0.1-e848ecb-bullseye -- bash -c ' - wget http://673156464838-mina-genesis-ledgers.s3-website-us-west-2.amazonaws.com/mainnet/genesis_ledger.json; mina-berkeley-migration-script initial \ - --genesis-ledger genesis_ledger.json \ - --source-db postgres://mina:minamina@postgres:5432/mainnet_balances_migrated \ - --target-db postgres://mina:minamina@postgres:5432/mainnet_really_migrated \ - --blocks-batch-size 5000 \ - --blocks-bucket mina_network_block_data \ - --checkpoint-output-path /data/checkpoints/. \ - --precomputed-blocks-local-path /data/precomputed_blocks/. \ - --network mainnet' - -docker start mainnet-db-migration - -docker logs -f mainnet-db-migration - -``` diff --git a/docs/berkeley-upgrade/archive-migration/index.mdx b/docs/berkeley-upgrade/archive-migration/index.mdx deleted file mode 100644 index e43dcf017..000000000 --- a/docs/berkeley-upgrade/archive-migration/index.mdx +++ /dev/null @@ -1,48 +0,0 @@ ---- -title: Archive Migration -sidebar_label: Archive Migration -hide_title: true -description: Berkeley upgrade is a major upgrade that requires all nodes in a network to upgrade to a newer version. It is not backward compatible. -keywords: - - Berkeley - - upgrade - - archive migration - - mina archive node - - archive node ---- - -# Archive Migration - -The Berkeley upgrade is a major upgrade that requires all nodes in a network to upgrade to a newer version. It is not backward compatible. - -A major upgrade occurs when there are major changes to the core protocol that require all nodes on the network to update to the latest software. - -## How to prepare for the Berkeley upgrade - -The Berkeley upgrade requires upgrading all nodes, including archive nodes. One of the required steps is to migrate archive databases from the current Mainnet format to Berkeley. This migration requires actions and efforts from node operators and exchanges. - -Learn about the archive data migration: - -- [Understanding the migration process](/berkeley-upgrade/archive-migration/understanding-archive-migration) -- [Prerequisites before migration](/berkeley-upgrade/archive-migration/archive-migration-prerequisites) -- [Suggested installation procedure](/berkeley-upgrade/archive-migration/archive-migration-installation) -- [How to perform archive migration](/berkeley-upgrade/archive-migration/migrating-archive-database-to-berkeley) - -Finally, see the shell script example that is compatible with a stock Debian 11 container: - -- [Worked Devnet Debian example using March 22 data](/berkeley-upgrade/archive-migration/debian-example) -- [Worked Mainnet Docker example using April 29 data](/berkeley-upgrade/archive-migration/docker-example) - -## What will happen with original Devnet/Mainnet data - -After the migration, you will have two databases: - -- The original Devnet/Mainnet database with small data adjustments (all pending blocks from last canoncial block until the fork block are converted to canoncial blocks) -- A new Berkeley database based on Devnet/Mainnet data, but: - - Without Devnet/Mainnet orphaned blocks - - Without pending blocks that are not in the canonical chain - - With all pending blocks on the canonical chain converted to canonical blocks - -There is no requirement to preserve the original Devnet/Mainnet database after migration. However, if for some reason you want to keep the Mainnet orphaned or non-canonical pending blocks, you can download the archive maintenance package for the Devnet/Mainnet database. - -To learn about maintaining archive data, see [Devnet/Mainnet database maintenance](/berkeley-upgrade/archive-migration/mainnet-database-maintenance). diff --git a/docs/berkeley-upgrade/archive-migration/mainnet-database-maintenance.mdx b/docs/berkeley-upgrade/archive-migration/mainnet-database-maintenance.mdx deleted file mode 100644 index 5d8a7abde..000000000 --- a/docs/berkeley-upgrade/archive-migration/mainnet-database-maintenance.mdx +++ /dev/null @@ -1,196 +0,0 @@ ---- -title: Devnet/Mainnet database maintenance -sidebar_label: Devnet/Mainnet database maintenance -hide_title: true -description: Steps to properly maintain correctness of archive database. -keywords: - - Berkeley - - upgrade - - archive migration - - planning - - prerequisites - - mina archive node - - archive node - - mainnet - - devnet - - database ---- - -# Devnet/Mainnet database maintenance - -After the Berkeley migration, the original Devnet/Mainnet database is not required unless you are interested in -preserving some aspect of the database that is lost during the migration process. - -Two databases exist after the successful migration: - -- The original Devnet/Mainnet database with small data adjustments: - - All pending blocks from last canoncial block until the fork block are converted to canonical blocks - -- A new Berkeley database based on Devnet/Mainnet data with these differences: - - Without Devnet/Mainnet orphaned blocks - - Without pending blocks that are not in the canonical chain - - With all pending blocks on the canonical chain converted to canonical blocks - -The o1Labs and Mina Foundation teams have consistently prioritized rigorous testing and the delivery of high-quality software products. - -However, being human entails the possibility of making mistakes. - -## Known issues - -Recently, a few mistakes were identified while working on a version of Mina used on Mainnet. These issues were promptly addressed; however, within the decentralized environment, archive nodes can retain historical issues despite our best efforts. - -Fixes are available for the following known issues: - -- **Missing or invalid nonces** - a historical issue skewed nonces in the `balances` table. Although the issue was resolved, you might still have nonces that are missing or invalid. -- **Incorrect ledger hashes** - a historical issue with the same root cause as 'Missing or invalid nonces'. However, the outcome is that a 'replayer run' operation of validating archive node against daemon ledger shows ledger mismatches and cannot pass problematic blocks. -- **Missing blocks** - This recurring missing blocks issue consistently poses challenges and is a source of concern for all archive node operators. This persistent challenge from disruptions in daemon node operations can potentially lead to incomplete block reception by archive nodes. This situation can compromise chain continuity within the archive database. - -To address these issues, install and use the special archive node maintenance package that includes fixes. - -## Installing the archive node maintenance package - -The package provides support for codenames: - -- bullseye -- buster -- focal - -The following steps describe only the bullseye package installation. Modify the steps as appropriate for your environment. - -### Debian packages - -To get the Debian package: - -```sh -CODENAME=bullseye -CHANNEL=stable -VERSION=1.4.1 - -echo "deb [trusted=yes] http://packages.o1test.net $CODENAME $CHANNEL" | tee /etc/apt/sources.list.d/mina.list -apt-get update -apt-get install --allow-downgrades -y "mina-archive-maintenance=$VERSION" -``` - -### Docker image - -To get the Docker image: - -```sh -docker pull gcr.io/o1labs-192920/mina-archive-maintenance:1.4.1 -``` - -## Usage for missing or invalid nonces - -The replayer application was developed to verify the Devnet/Mainnet archive data. You must run the replayer application against your existing Devnet/Mainnet database to verify the blockchain state. - -To run the replayer application: - -```sh -mina-replayer \ - --archive-uri {db_connection_string} \ - --input-file reference_replayer_input.json \ - --output-file replayer_input_file.json \ - --checkpoint-interval 10000 \ - --fix-nonces \ - --set-nonces \ - --dump-repair-script -``` - -where: - -- `archive-uri` - connection string to the archive database -- `input-file` - JSON file that holds the archive database -- `output-file` - JSON file that will hold the ledger with auxiliary information, like global slot and blockchain height, which will be dumped on the last block -- `checkpoint-interval` - frequency of checkpoints expressed in blocks count -- `replayer_input_file.json` - JSON file constructed from the Devnet/Mainnet genesis ledger: - - ```sh - jq '.ledger.accounts' genesis_ledger.json | jq '{genesis_ledger: {accounts: .}}' > replayer_input_config.json - ``` - -- `--fix-nonces` - adjust nonces values while replaying transactions -- `--set-nonces` - set missing nonces while replaying transactions -- `--dump-repair-script` - path to the output SQL script that will contain all updates to nonces made during the replayer run that can be directly applied to other database instances that contain the same data with invalid nonces - -Running a replayer from scratch on a Devnet/Mainnet database can take up to a couple of days. The recommended best practice is to break the replayer into smaller parts by using the checkpoint capabilities of the replayer. -Additionally, running the replayer can exert significant demands on system resources that potentially affect the performance of the archive node. Because of the large resource requirements, we recommend that you execute the replayer in isolation from network connections, preferably within an isolated environment where the Devnet/Mainnet dumps can be imported. - -## Bad ledger hashes - -There is no ultimate fix for this issue because preserving historical ledger hashes is essential to the overall security of the Mina network. Even with this issue, you can validate archive data integrity. - -The replayer application has a built-in mechanism to skip errors when the `--continue-on-error` flag is enabled. -However, instead of skipping only blocks with bad ledger hashes, this mode skipped all of the problems with integrity. -With the new archive node maintenance package, you can run the replayer application without a special flag and to correctly handle the bad ledger hashes issue. - -To run replayer: - -```sh -mina-replayer --archive-uri {db_connection_string} --input-file reference_replayer_input.json --output-file reference_replayer_output.json --checkpoint-interval 10000 -``` - -where: - -- `archive-uri` - connection string to the archive database -- `input-file` - JSON file that holds the archive database -- `output-file` - JSON file that will hold the ledger with auxiliary information, like global slot and blockchain height, which will be dumped on the last block -- `checkpoint-interval` - frequency of checkpoints expressed in blocks count -- `replayer_input_file.json` - JSON file constructed from the Devnet/Mainnet genesis ledger: - - ``` - jq '.ledger.accounts' genesis_ledger.json | jq '{genesis_ledger: {accounts: .}}' > replayer_input_config.json - ``` - -:warning: Running a replayer from scratch on a Devnet/Mainnet database can take up to a couple of days. The recommended best practice is to break the replayer into smaller parts by using the checkpoint capabilities of the replayer. - -:warning: You must run the replayer using the Mainnet version. You can run it from the Docker image at `gcr.io/o1labs-192920/mina-archive:2.0.0-039296a-bullseye`. - -## Missing blocks - -The daemon node unavailability can cause the archive node to miss some of the blocks. This recurring missing blocks issue consistently poses challenges. To address this issue, you can reapply missing blocks. - -If you uploaded the missing blocks to Google Cloud, the missing blocks can be reapplied from precomputed blocks to preserve chain continuity. - -1. To automatically verify and patch missing blocks, use the [download_missing_blocks.sh](https://raw.githubusercontent.com/MinaProtocol/mina/2.0.0berkeley_rc1/src/app/rosetta/download-missing-blocks.sh) script. - - The `download-missing-blocks` script uses `localhost` as the database host so the script assumes that psql is running on localhost on port 5432. Modify `PG_CONN` in `download_missing_block.sh` for your environment. - -1. Install the required `mina-archive-blocks` and `mina-missing-blocks-auditor` scripts that are packed in the `gcr.io/o1labs-192920/mina-archive:2.0.0-039296a-bullseye` Docker image. - -1. Export the `BLOCKS_BUCKET`: - - ```sh - export BLOCKS_BUCKET="https://storage.googleapis.com/my_bucket_with_precomputed_blocks" - ``` - -1. Run the `mina-missing-blocks-auditor` script from the database host: - - For Devnet: - - ```sh - download-missing-blocks.sh devnet {db_user} {db_password} - ``` - - For Mainnet: - - ```sh - download-missing-blocks.sh mainnet {db_user} {db_password} - ``` -### Using precomputed blocks from O1labs bucket - -O1labs maintains a Google bucket containing precomputed blocks from Devnet and Mainnet, accessible at https://storage.googleapis.com/mina_network_block_data/. - -Note: It's important to highlight that precomputed blocks for **Devnet** between heights `2` and `1582` have missing fields or incorrect transaction data. Utilizing these blocks to patch your Devnet archive database will result in failure. For those who rely on precomputed blocks from this bucket, please follow the outlined steps: - -1. Download additional blocks from `gs://mina_network_block_data/devnet-extensional-bundle.tar.gz`. -2. Install the necessary `mina-archive-blocks` script contained within the `gcr.io/o1labs-192920/mina-archive:2.0.0-039296a-bullseye` Docker image. -3. Execute mina-archive-blocks to import the extracted blocks from step 1 using the provided command: - - ```sh - mina-archive-blocks --archive-uri --extensional ./extensional/* - ``` -4. Proceed with patching your Devnet database with blocks having heights other than `2` to `1582` using the available precomputed blocks. - -## Next steps - -Now that you have completed the steps to properly maintain the correctness of the archive database, you are ready to perform the archive [migration process](/berkeley-upgrade/archive-migration/migrating-archive-database-to-berkeley). diff --git a/docs/berkeley-upgrade/archive-migration/migrating-archive-database-to-berkeley.mdx b/docs/berkeley-upgrade/archive-migration/migrating-archive-database-to-berkeley.mdx deleted file mode 100644 index 304a0068b..000000000 --- a/docs/berkeley-upgrade/archive-migration/migrating-archive-database-to-berkeley.mdx +++ /dev/null @@ -1,632 +0,0 @@ ---- -title: Migrating Devnet/Mainnet Archive to Berkeley Archive -sidebar_label: Performing archive migration -hide_title: true -description: Steps to properly migrate archives from Devnet/Mainnet to Berkeley. -keywords: - - Berkeley - - upgrade - - archive migration - - planning - - prerequisites - - mina archive node - - archive node ---- - -# Migrating Devnet/Mainnet Archive to Berkeley Archive - -Before you start the process to migrate your archive database from the current Mainnet or Devnet format to Berkeley, be sure that you: - -- [Understand the Archive Migration](/berkeley-upgrade/archive-migration/understanding-archive-migration) -- Meet the foundational requirements in [Archive migration prerequisites](/berkeley-upgrade/archive-migration/archive-migration-prerequisites) -- Have successfully installed the [archive migration package](/berkeley-upgrade/archive-migration/archive-migration-installation) - -## Migration process - -The Devnet/Mainnet migration can take up to a couple of days. -Therefore, you can achieve a successful migration by using three stages: - -- **Stage 1:** Initial migration - -- **Stage 2:** Incremental migration - -- **Stage 3:** Remainder migration - -Each stage has three migration phases: - -- **Phase 1:** Copying data and precomputed blocks from Devnet/Mainnet database using the **berkeley_migration** app. - -- **Phase 2:** Populating new Berkeley tables using the **replayer app in migration mode** - -- **Phase 3:** Additional validation for migrated database - -Review these phases and stages before you start the migration. - -## Simplified approach - -For convenience, use the `mina-berkeley-migration-script` app if you do not need to delve into the details of migration or if your environment does not require a special approach to migration. - -### Stage 1: Initial migration - -``` -mina-berkeley-migration-script \ - initial \ - --genesis-ledger ledger.json \ - --source-db postgres://postgres:postgres@localhost:5432/source \ - --target-db postgres://postgres:postgres@localhost:5432/migrated \ - --blocks-bucket mina_network_block_data \ - --blocks-batch-size 500 \ - --checkpoint-interval 10000 \ - --checkpoint-output-path . \ - --precomputed-blocks-local-path . \ - --network NETWORK -``` - -where: - -`-g | --genesis-ledger`: path to the genesis ledger file - -`-s | --source-db`: connection string to the database to be migrated - -`-t | --target-db`: connection string to the database that will hold the migrated data - -`-b | --blocks-bucket`: name of the precomputed blocks bucket. Precomputed blocks are assumed to be named with format: `{network}-{height}-{state_hash}.json` - -`-bs | --blocks-batch-size`: number of precomputed blocks to be fetched at one time from Google Cloud. A larger number, like 1000, can help speed up the migration process. - -`-n | --network`: network name (`devnet` or `mainnet`) when determining precomputed blocks. Precomputed blocks are assumed to be named with format: `{network}-{height}-{state_hash}.json`. - -`-c | --checkpoint-output-path`: path to folder for replayer checkpoint files - -`-i | --checkpoint-interval`: frequency of dumping checkpoint expressed in blocks count - -`-l | --precomputed-blocks-local-path`: path to folder for on-disk precomputed blocks location - -The command output is the `migration-replayer-XXX.json` file required for the next run. - -### Stage 2: Incremental migration - -``` -mina-berkeley-migration-script \ - incremental \ - --genesis-ledger ledger.json \ - --source-db postgres://postgres:postgres@localhost:5432/source \ - --target-db postgres://postgres:postgres@localhost:5432/migrated \ - --blocks-bucket mina_network_block_data \ - --blocks-batch-size 500 \ - --network NETWORK \ - --checkpoint-output-path . \ - --checkpoint-interval 10000 \ - --precomputed-blocks-local-path . \ - --replayer-checkpoint migration-checkpoint-XXX.json -``` - -where: - -`-g | --genesis-ledger`: path to the genesis ledger file - -`-s | --source-db`: connection string to the database to be migrated - -`-t | --target-db`: connection string to the database that will hold the migrated data - -`-b | --blocks-bucket`: name of the precomputed blocks bucket. Precomputed blocks are assumed to be named with format: `{network}-{height}-{state_hash}.json` - -`-bs | --blocks-batch-size`: number of precomputed blocks to be fetched at one time from Google Cloud. A larger number, like 1000, can help speed up migration process. - -`-n | --network`: network name (`devnet` or `mainnet`) when determining precomputed blocks. Precomputed blocks are assumed to be named with format: `{network}-{height}-{state_hash}.json`. - -`-r | --replayer-checkpoint`: path to the latest checkpoint file `migration-checkpoint-XXX.json` - -`-c | --checkpoint-output-path`: path to folder for replayer checkpoint files - -`-i | --checkpoint-interval`: frequency of dumping checkpoint expressed in blocks count - -`-l | --precomputed-blocks-local-path`: path to folder for on-disk precomputed blocks location - -### Stage 3: Remainder migration - -``` -mina-berkeley-migration-script \ - final \ - --genesis-ledger ledger.json \ - --source-db postgres://postgres:postgres@localhost:5432/source \ - --target-db postgres://postgres:postgres@localhost:5432/migrated \ - --blocks-bucket mina_network_block_data \ - --blocks-batch-size 500 \ - --network NETWORK \ - --checkpoint-output-path . \ - --checkpoint-interval 10000 \ - --precomputed-blocks-local-path . \ - --replayer-checkpoint migration-checkpoint-XXX.json \ - -fc fork-genesis-config.json -``` - -where: - -`-g | --genesis-ledger`: path to the genesis ledger file - -`-s | --source-db`: connection string to the database to be migrated - -`-t | --target-db`: connection string to the database that will hold the migrated data - -`-b | --blocks-bucket`: name of the precomputed blocks bucket. Precomputed blocks are assumed to be named with format: `{network}-{height}-{state_hash}.json` - -`-bs | --blocks-batch-size`: number of precomputed blocks to be fetched at one time from Google Cloud. A larger number, like 1000, can help speed up the migration process. - -`-n | --network`: network name (`devnet` or `mainnet`) when determining precomputed blocks. Precomputed blocks are assumed to be named with format: `{network}-{height}-{state_hash}.json`. - -`-r | --replayer-checkpoint`: path to the latest checkpoint file `migration-checkpoint-XXX.json` - -`-c | --checkpoint-output-path`: path to folder for replayer checkpoint files - -`-i | --checkpoint-interval`: frequency of dumping checkpoint expressed in blocks count - -`-l | --precomputed-blocks-local-path`: path to folder for on-disk precomputed blocks location - -`-fc | --fork-config`: fork genesis config file is the new genesis config that is distributed with the new daemon and is published after the fork block is announced - -## Advanced approach - -If the simplified berkeley migration script is, for some reason, not suitable for you, it is possible to run the migration using the **berkeley_migration** and **replayer** apps without an interface the script provides. - -### Stage 1: Initial migration - -This first stage requires only the initial Berkeley schema, which is the foundation for the next migration stage. This schema populates the migrated database and creates an initial checkpoint for further incremental migration. - -- Inputs - - Unmigrated Devnet/Mainnet database - - Devnet/Mainnet genesis ledger - - Empty target Berkeley database with the schema created, but without any content - -- Outputs - - Migrated Devnet/Mainnet database to the Berkeley format from genesis up to the last canonical block in the original database - - Replayer checkpoint that can be used for incremental migration - -#### Phase 1: Berkeley migration app run - -``` -mina-berkeley-migration \ - --batch-size 1000 \ - --config-file ledger.json \ - --mainnet-archive-uri postgres://postgres:postgres@localhost:5432/source \ - --migrated-archive-uri postgres://postgres:postgres@localhost:5432/migrated \ - --blocks-bucket mina_network_block_data \ - --precomputed-blocks-local-path . \ - --keep-precomputed-blocks \ - --network NETWORK -``` - -where: - -`--batch-size`: number of precomputed blocks to be fetched at one time from Google Cloud. A larger number, like 1000, can help speed up migration process. - -`--config-file`: path to the genesis ledger file - -`--mainnet-archive-uri`: connection string to the database to be migrated - -`--migrated-archive-uri`: connection string to the database that will hold the migrated data - -`--blocks-bucket`: name of the precomputed blocks bucket. Precomputed blocks are assumed to be named with format: `{network}-{height}-{state_hash}.json` - -`--precomputed-blocks-local-path`: path to folder for on-disk precomputed blocks location - -`--keep-precomputed-blocks`: keep the precomputed blocks on-disk after the migration is complete - -`--network`: the network name (`devnet` or `mainnet`) when determining precomputed blocks. Precomputed blocks are assumed to be named with format: `{network}-{height}-{state_hash}.json` - -#### Phase 2: Replayer in migration mode run - -Replayer config must contain the Devnet/Mainnet ledger as the starting point. So first, you must prepare the replayer config file: - -``` - jq '.ledger.accounts' genesis_ledger.json | jq '{genesis_ledger: {accounts: .}}' > replayer_input_config.json -``` - -where: - - `genesis_ledger.json` is the genesis file from a daemon bootstrap on a particular network - -Then: -``` - mina-migration-replayer \ - --migration-mode \ - --archive-uri postgres://postgres:postgres@localhost:5432/migrated \ - --input-file replayer_input_config.json \ - --checkpoint-interval 10000 \ - --checkpoint-output-folder . -``` - -where: - -`--migration-mode`: flag for migration - -`--archive-uri`: connection string to the database that will hold the migrated data - -`--input-file`: path to the replayer input file, see below on how's created - -`replayer_input_config.json`: is a file constructed out of network genesis ledger: - ``` - jq '.ledger.accounts' genesis_ledger.json | jq '{genesis_ledger: {accounts: .}}' > replayer_input_config.json - ``` - -`--checkpoint-interval`: frequency of checkpoints file expressed in blocks count - -`--checkpoint-output-folder`: path to folder for replayer checkpoint files - -#### Phase 3: Validations - -Use the **berkeley_migration_verifier** app to perform checks for both the fully migrated and partially migrated databases. - -``` - mina-berkeley-migration-verifier \ - pre-fork \ - --mainnet-archive-uri postgres://postgres:postgres@localhost:5432/source \ - --migrated-archive-uri postgres://postgres:postgres@localhost:5432/migrated -``` - -where: - -`--mainnet-archive-uri`: connection string to the database to be migrated - -`--migrated-archive-uri`: connection string to the database that will hold the migrated data - -### Stage 2: Incremental migration - -After the initial migration, the data is migrated data up to the last canonical block. However, Devnet/Mainnet data is progressing with new blocks that must also be migrated again and again until the fork block is announced. - -:::info -Incremental migration can, and probably must, be repeated a couple of times until the fork block is announced by Mina Foundation. -Run the incremental migration multiple times with the latest Devnet/Mainnet database and the latest replayer checkpoint file. -::: - -- Inputs - - Latest Devnet/Mainnet database - - Devnet/Mainnet genesis ledger - - Replayer checkpoint from last run - - Migrated berkeley database from initial migration - -- Outputs - - Migrated Devnet/Mainnet database to the Berkeley format up to the last canonical block - - Replayer checkpoint which can be used for the next incremental migration - -### Phase 1: Berkeley migration app run - -``` -mina-berkeley-migration \ - --batch-size 1000 \ - --config-file ledger.json \ - --mainnet-archive-uri postgres://postgres:postgres@localhost:5432/source \ - --migrated-archive-uri postgres://postgres:postgres@localhost:5432/migrated \ - --blocks-bucket mina_network_block_data \ - --precomputed-blocks-local-path . \ - --keep-precomputed-blocks \ - --network NETWORK -``` - -where: - -`--batch-size`: number of precomputed blocks to be fetched at one time from Google Cloud. A larger number, like 1000, can help speed up migration process. - -`--config-file`: path to the genesis ledger file - -`--mainnet-archive-uri`: connection string to the database to be migrated - -`--migrated-archive-uri`: connection string to the database that will hold the migrated data - -`--blocks-bucket`: name of the precomputed blocks bucket. Precomputed blocks are assumed to be named with format: `{network}-{height}-{state_hash}.json` - -`--precomputed-blocks-local-path`: path to folder for on-disk precomputed blocks location - -`--keep-precomputed-blocks`: keep the precomputed blocks on-disk after the migration is complete - -`--network`: the network name (`devnet` or `mainnet`) when determining precomputed blocks. Precomputed blocks are assumed to be named with format: `{network}-{height}-{state_hash}.json` - -#### Phase 2: Replayer in migration mode run - -``` - mina-migration-replayer \ - --migration-mode \ - --archive-uri postgres://postgres:postgres@localhost:5432/migrated \ - --input-file replayer-checkpoint-XXX.json \ - --checkpoint-interval 10000 \ - --checkpoint-output-folder . -``` - -where: - -`--migration-mode`: flag for migration - -`--archive-uri`: connection string to the database that will hold the migrated data - -`--input-file`: path to the latest checkpoint file `replayer-checkpoint-XXX.json` - -`replayer-checkpoint-XXX.json`: the latest checkpoint generated from the previous migration - -`--checkpoint-interval`: frequency of checkpoints file expressed in blocks count - -`--checkpoint-output-folder`: path to folder for replayer checkpoint files - -Incremental migration can be run continuously on top of the initial migration or last incremental until the fork block is announced. - -#### Phase 3: Validations - -Use the **berkeley_migration_verifier** app to perform checks for both the fully migrated and partially migrated database. - -``` - mina-berkeley-migration-verifier \ - pre-fork \ - --mainnet-archive-uri postgres://postgres:postgres@localhost:5432/source \ - --migrated-archive-uri postgres://postgres:postgres@localhost:5432/migrated -``` - -where: - -`--mainnet-archive-uri`: connection string to the database to be migrated - -`--migrated-archive-uri`: connection string to the database that will hold the migrated data - -Note that: you can run incremental migration continuously on top of the initial migration or the last incremental until the fork block is announced. - -### Stage 3: Remainder migration - -When the fork block is announced, you must tackle the remainder migration. This is the last migration run -you need to perform. In this stage, you close the migration cycle with the last migration of the remainder blocks between the current last canonical block and the fork block (which can be pending, so you don't need to wait 290 blocks until it would become canonical). -You must use `--fork-state-hash` as an additional parameter to the **berkeley-migration** app. - -- Inputs - - Latest Devnet/Mainnet database - - Devnet/Mainnet genesis ledger - - Replayer checkpoint from last run - - Migrated Berkeley database from last run - - Fork block state hash - -- Outputs - - Migrated devnet/mainnet database to berkeley up to fork point - - Replayer checkpoint which can be used for the next incremental migration - -:::info -The migrated database output from this stage of the final migration is required to initialize your archive nodes on the upgraded network. -::: - -#### Phase 1: Berkeley migration app run - -``` -mina-berkeley-migration \ - --batch-size 1000 \ - --config-file ledger.json \ - --mainnet-archive-uri postgres://postgres:postgres@localhost:5432/source \ - --migrated-archive-uri postgres://postgres:postgres@localhost:5432/migrated \ - --blocks-bucket mina_network_block_data \ - --precomputed-blocks-local-path \ - --keep-precomputed-blocks \ - --network NETWORK \ - --fork-state-hash {fork-state-hash} -``` - -where: - -`--batch-size`: number of precomputed blocks to be fetched at one time from Google Cloud. A larger number, like 1000, can help speed up migration process. - -`--config-file`: path to the genesis ledger file - -`--mainnet-archive-uri`: connection string to the database to be migrated - -`--migrated-archive-uri`: connection string to the database that will hold the migrated data - -`--blocks-bucket`: name of the precomputed blocks bucket. Precomputed blocks are assumed to be named with format: `{network}-{height}-{state_hash}.json` - -`--precomputed-blocks-local-path`: path to folder for on-disk precomputed blocks location - -`--keep-precomputed-blocks`: keep the precomputed blocks on-disk after the migration is complete - -`--network`: the network name (`devnet` or `mainnet`) when determining precomputed blocks. Precomputed blocks are assumed to be named with format: `{network}-{height}-{state_hash}.json` - -`--fork-state-hash`: fork state hash - -:::info -When you run the **berkeley-migration** app with fork-state-hash, there is no requirement for the fork state block to be canonical. -The tool automatically converts all pending blocks in the subchain, including the fork block, to canonical blocks. -::: - -#### Phase 2: Replayer in migration mode run - -``` -mina-migration-replayer \ - --migration-mode \ - --archive-uri postgres://postgres:postgres@localhost:5432/migrated \ - --input-file replayer-checkpoint-XXX.json \ - --checkpoint-interval 10000 \ - --checkpoint-output-folder . -``` - -where: - -`--migration-mode`: flag for migration - -`--archive-uri`: connection string to the database that will hold the migrated data - -`--input-file`: path to the latest checkpoint file `replayer-checkpoint-XXX.json` from stage 1 - -`replayer-checkpoint-XXX.json`: the latest checkpoint generated from the previous migration - -`--checkpoint-interval`: frequency of checkpoints file expressed in blocks count - -`--checkpoint-output-folder`: path to folder for replayer checkpoint files - -#### Phase 3: Validations - -Use the **berkeley_migration_verifier** app to perform checks for both the fully migrated and partially migrated databases. - -``` - mina-berkeley-migration-verifier \ - post-fork \ - --mainnet-archive-uri postgres://postgres:postgres@localhost:5432/source \ - --migrated-archive-uri postgres://postgres:postgres@localhost:5432/migrated \ - --fork-config-file fork_genesis_config.json \ - --migrated-replayer-output replayer-checkpoint-XXXX.json -``` - -where: - -`--mainnet-archive-uri`: connection string to the database to be migrated - -`--migrated-archive-uri`: connection string to the database that will hold the migrated data - -`--migrated-replayer-output`: path to the latest checkpoint file `replayer-checkpoint-XXX.json` - -`--fork-config`: fork genesis config file is the new genesis config that is distributed with the new daemon and is published after the fork block is announced - -### Example migration steps using Mina Foundation data for Devnet using Debian - -See: [Worked example using March 22 data](/berkeley-upgrade/archive-migration/debian-example) - -### Example migration steps using Mina Foundation data for Mainnet using Docker - -See: [Worked example using March 22 data](/berkeley-upgrade/archive-migration/docker-example) - -## How to verify a successful migration - -o1Labs and Mina Foundation make every effort to provide reliable tools of high quality. However, it is not possible to eliminate all errors and test all possible Mainnet archive variations. -All important checks are implemented in the `mina-berkeley-migration-verifier` application. -However, you can use the following checklist if you want to perform the checks manually: - -1. All transaction (user command and internal command) hashes are left intact. - - Verify that the `user_command` and `internal_command` tables have the Devnet/Mainnet format of hashes. For example, `CkpZirFuoLVV...`. - -2. Parent-child block relationship is preserved - - Verify that a given block in the migrated archive has the same parent in the Devnet/Mainnet archive (`state_hash` and `parent_hash` columns) that was used as input. - -3. Account balances remain the same - - Verify the same balance exists for a given block in Mainnet and the migrated databases. - -## Tips and tricks - -We are aware that the migration process can be very long (a couple of days). Therefore, we encourage you to use cron jobs that migrate data incrementally. -The cron job requires access to Google Cloud buckets (or other storage): - -- A bucket to store migrated-so-far database dumps -- A bucket to store checkpoint files - -We are tightly coupled with Google Cloud infrastructure due to the precomputed block upload mechanism. -This is why we are using also buckets for storing dumps and checkpoint. However, you do not have to use Google Cloud for other things than -precomputed blocks. With configuration, you can use any gsutil-compatible storage backend (for example, S3). - -Before running the cron job, upload an initial database dump and an initial checkpoint file. - -To create the files, run these steps locally: - -1. Download a Devnet/Mainnet archive dump and load it into PostgreSQL. -2. Create an empty database using the new archive schema. -3. Run the **berkeley-migration** app against the Devnet/Mainnet and new databases. -4. Run the **replayer app in migration mode** with the `--checkpoint-interval` set to a suitable value (perhaps 100) and start with the original Devnet/Mainnet ledger in the input file. -5. Use pg_dump to dump the migrated database and upload it. -6. Upload the most recent checkpoint file. - -The cron job performs the same steps in an automated fashion: - -1. Pulls the latest Devnet/Mainnet archive dump and loads it into PostgresQL. -2. Pulls the latest migrated database and loads it into PostgreSQL. -3. Pulls the latest checkpoint file. -4. Runs the **berkeley-migration** app against the two databases. -5. Runs the **replayer app in migration mode** using the downloaded checkpoint file; set the checkpoint interval to be smaller (perhaps 50) because there are typically only 200 or so blocks in a day. -7. Uploads the migrated database. -8. Uploads the most recent checkpoint file. - -Be sure to monitor the cron job for errors. - -Just before the Berkeley upgrade, migrate the last few blocks by running locally: - -1. Download the Devnet/Mainnet archive data directly from the k8s PostgreSQL node (not from the archive dump), and load it into PostgreSQL. -2. Download the most recent migrated database and load it into PostgresQL. -3. Download the most recent checkpoint file. -4. Run the **berkeley-migration** app against the two databases. -5. Run the **replayer app in migration mode** using the most recent checkpoint file. - -It is worthwhile to perform these last steps as a dry run to make sure all goes well. You can run these steps as many times as needed. - -## Known migration problems - -Please remember that rerunning after crash is always possible. -After solving any of below issues you can rerun process and migration -will continue form last position - -#### Async was unable to add a file descriptor to its table of open file descriptors -For example: - -``` - ("Async was unable to add a file descriptor to its table of open file descriptors" - (file_descr 18) - (error - "Attempt to register a file descriptor with Async that Async believes it is already managing.") - (backtrace - ...... -``` -A remedy is to lower `--block-batch-size` parameter to values up to 500. - -#### Map.find_exn: not found -For example: -``` -(monitor.ml.Error - (Not_found_s - ("Map.find_exn: not found" -.... -``` - -Usually this error means that there is a gap in canonical chain. In order to fix it please -ensure that missing-block-auditor run is successful - -#### Yojson.Json_error .. Unexpected end of input - -For example: - -``` -(monitor.ml.Error - ("Yojson.Json_error(\"Line 1, bytes 1003519-1003520:\\nUnexpected end of input\")") - ("Raised at Yojson.json_error in file \"common.ml\", line 5, characters 19-39" - "Called from Yojson.Safe.__ocaml_lex_read_json_rec in file \"lib/read.mll\", line 215, characters 28-52" -... -``` - -This issue is caused by invalid precomputed block. Deleting the downloaded precomputed blocks should resolve this issue. - -#### Error querying db, error: Request to ... failed: ERROR: column \"type\" does not exist - -You provided the migrated schema as source one when invoking script or berkeley-migration app - -#### Poor performance of migration when accessing remote database - -We conducted migration tests with both a local database and a distant database (RDS). -The migration using the local database appears to process significantly faster. We strongly suggest to use offline database installed locally - -#### ERROR: out of shared memory - -``` -(monitor.ml.Error (Failure "Error querying for user commands with id 1686617, error Request to postgresql://user:pwd@host:port/db failed: ERROR: out of shared memory -\nHINT: You might need to increase max_pred_locks_per_transaction -``` - -Solution is either to increase `max_pred_locks_per_transaction` setting in postgres database. -Alternative is to isolate database from mainnet traffic (for example by exporting dump from live database and import it on isolated environment) - -#### Berkeley migration app is consuming all of my resources - -When running a full migration, you can stumble on memory leaks that prevent you from cleanly performing the migration in one pass. A machine with 64 GB of RAM can be frozen after ~40k migrated blocks. Each 200 blocks inserted into the database increases the memory leak by 4-10 MB. - -A potential workaround is to split the migration into smaller parts using cron jobs or automation scripts. - -## FAQ - -### Migrated database is missing orphaned blocks - -By design, Berkeley migration omits orphaned blocks and, by default, migrates only canonical (and pending, if setup correctly) blocks. - -### Replayer in migration mode overrides my old checkpoints - -By default, the replayer dumps the checkpoint to the current folder. All checkpoint files have a similar format: - -`replayer-checkpoint-{number}.json.` - -To prevent override of old checkpoints, use the `--checkpoint-output-folder` and `--checkpoint-file-prefix` parameters to modify the output folder and prefix. diff --git a/docs/berkeley-upgrade/archive-migration/understanding-archive-migration.mdx b/docs/berkeley-upgrade/archive-migration/understanding-archive-migration.mdx deleted file mode 100644 index d80a53eaa..000000000 --- a/docs/berkeley-upgrade/archive-migration/understanding-archive-migration.mdx +++ /dev/null @@ -1,56 +0,0 @@ ---- -title: Understanding archive migration -sidebar_label: Understanding archive migration -hide_title: true -description: Overview of the migration tools and requirements to successfully migrate Devnet/Mainnet archive database. -keywords: - - Berkeley - - upgrade - - archive migration - - planning - - prerequisites - - mina archive node - - archive node ---- - -# Understanding the Archive Migration - -You can reduce risks and effort by reading all of the archive documentation in entirety. - -## Archive node migration overview - -Archive node migration is a crucial part of the Berkeley upgrade. The current Devnet and Mainnet database format must be converted to the Berkeley format to preserve historical data and assure archive node chain continuity. - -For this purpose, the o1Labs and Mina Foundation teams prepared a migration package. - -### Archive node Berkeley migration package - -This package contains the required applications to migrate existing Devnet and Mainnet databases into the new Berkeley schema and a usability script: - -1. **berkeley-migration** - - Use the **berkeley-migration** app to migrate as much data as possible from the Devnet/Mainnet database and download precomputed blocks to get the window density data. - - This app runs against the Devnet/Mainnet database and the new Berkeley database. - -2. **replayer app in migration mode** - - The existing replayer application is enhanced with a new migration mode. Use the **replayer app in migration mode** to analyze the transactions in the partially migrated database (resulting from running berkeley-migration app) and populate the `accounts_accessed` and `accounts_created` tables. This app also does the checks performed by the standard replayer, but does not check ledger hashes because the Berkeley ledger has greater depth that results in different hashes. - - This app runs only against the new archive database. - -3. **berkeley-migration-verifier** - - Use the **berkeley-migration-verifier** verification software to determine if the migration (even incomplete) was successful. The app uses SQL validations on the migrated database. - -4. **end-to-end migration script** - - This shell script wraps all phases and stages of migration into a single script. It is provided purely for node operators usability and is equivalent of running the **berkely-migration** app, the **replayer app in migration mode**, and the **berkeley-migration-verifier** apps in the correct order. - -### Incrementality - -Use the **berkeley-migration** and **replayer** apps incrementally so that you can migrate part of the Devnet/Mainnet database, and, as new blocks are added to the Devnet/Mainnet databases, the new data can be migrated. - -To obtain that incrementality, the **berkeley-migration** app looks at the migrated database and determines the most recent migrated block. It continues migration starting at the next block in the Devnet/Mainnet data. The **replayer app in migration mode** uses the checkpoint mechanism already in place for the replayer. A checkpoint file indicates the global slot since genesis for starting the replay and the ledger to use for that replay. New checkpoint files are written as it proceeds. - -To take advantage of the incrementality, run a cron job that migrates a day's worth of data at a time (or some other interval). With the cron job in place, at the time of the actual Berkeley upgrade, you will need to migrate only a small amount of data. diff --git a/docs/berkeley-upgrade/upgrade-steps.mdx b/docs/berkeley-upgrade/upgrade-steps.mdx deleted file mode 100644 index 767c04f2e..000000000 --- a/docs/berkeley-upgrade/upgrade-steps.mdx +++ /dev/null @@ -1,132 +0,0 @@ ---- -title: Upgrade Steps -sidebar_label: Upgrade Steps -hide_title: true -description: Detailed upgrade steps and operators' tasks -keywords: - - Berkeley - - upgrade - - Detailed upgrade steps and operators' tasks ---- - -# Upgrade Steps - - Mainnet Upgrade steps - -Below it's the description in detail of all the upgrade steps and what which node operator type should do to in each step. - -## Pre-Upgrade - -- During the Pre-Upgrade phase, node operators should prepare for the upcoming upgrade. The most important steps are: - - Review the [upgrade readiness checklist](https://docs.google.com/document/d/1rTmJvyaK33dWjJXMOSiUIGgf8z7turxolGHUpVHNxEU/edit#heading=h.2hqz0ixwjk3f) to confirm they have covered the required steps. - - Upgrade their nodes to the 1.4.1 stable version - - Ensure servers are provisioned to run Berkeley nodes, meeting the new hardware requirements - - Upgrade their nodes to the node version [2.0.0](https://github.com/MinaProtocol/mina/releases/tag/2.0.0), with stop-slots, when this version becomes available - - Start the archive node initial migration if they run archive nodes and wish to perform the migration in a decentralized manner - -**Please note:** a simplified Node Status service will be part of the upgrade tooling and enabled by default in Pre-Upgrade release with the stop-slots ([2.0.0](https://github.com/MinaProtocol/mina/releases/tag/2.0.0)). This feature will allow for a safe upgrade by monitoring the amount of upgraded active stake. Only non-sensitive data will be reported. If operators are not comfortable sharing their node version, they will have the option to disable the node version reports by using the appropriate node flag `--node-stats-type none` - -### Block Producers and SNARK Workers -1. Review the [upgrade readiness checklist](https://docs.google.com/document/d/1rTmJvyaK33dWjJXMOSiUIGgf8z7turxolGHUpVHNxEU). -1. Provision servers that meet the minimum hardware requirements, including the new 32GB RAM requirement and support for _AVX_ and _BMI2_ CPU instructions. -1. Upgrade nodes to node version [2.0.0](https://github.com/MinaProtocol/mina/releases/tag/2.0.0) ([2.0.0](https://github.com/MinaProtocol/mina/releases/tag/2.0.0) has built-in stop slots). - -### Archive Node Operators and Rosetta Operators -- Two migration processes will be available to archive node operators: _trustless_ and _trustful_. If the archive node operator wants to perform the _trustless_ migration, they should follow these steps; otherwise, proceed to the Upgrade phase. The _trustful_ migration will rely on o1Labs database exports and Docker images to migrate the archive node database and doesn’t require any actions at this stage. - -1. Trustless migration: - - Perform the initial archive node migration. Since Mainnet is a long-lived network, the initial migration process can take up to 48 hours, depending on your server specification and infrastructure. - - If your Mina Daemon, archive node, or PostgreSQL database runs on different machines, the migration performance will be greatly impacted. - - For more information on the archive node migration process, please refer to the [Archive Migration](/berkeley-upgrade/archive-migration) section. -2. Upgrade all nodes to the latest stable version [2.0.0](https://github.com/MinaProtocol/mina/releases/tag/2.0.0). -3. Provision servers that meet the minimum hardware requirements, primarily the new 32GB RAM requirement. -4. Upgrade their nodes to the version that includes built-in stop slots before the pre-defined _stop-transaction-slot_. - -### Exchanges -1. Make sure to test your system integration with Berkeley's new features. Pay special attention to: - - If you use the **o1labs/client-sdk** library to sign transactions, you should switch to **mina-signer** https://www.npmjs.com/package/mina-signer. **o1labs/client-sdk was deprecated some time ago and will be unusable** once the network has been upgraded. Please review the migration instructions in [Appendix](/berkeley-upgrade/appendix) - - If you rely on the archive node SQL database tables, please review the schema changes in Appendix 1 of this document. -2. Upgrade all nodes to the latest stable version [2.0.0](https://github.com/MinaProtocol/mina/releases/tag/2.0.0). -3. Provision servers that meet the minimum hardware requirements, particularly the new 32GB RAM requirement. -4. Upgrade your nodes to the version that includes built-in stop slots before the pre-defined _stop-transaction-slot_. - -*** - -## State Finalization -- Between the predefined _stop-transaction-slot_ and _stop-network-slot_, a stabilization period of 100 slots will occur. During this phase, the network consensus will not accept new blocks with transactions on them, including coinbase transactions. The state finalization period ensures all nodes reach a consensus on the latest network state before the upgrade. -- During the state finalization slots, it is crucial to maintain a high block density. Therefore, block producers and SNARK workers shall continue running their nodes to support the network's stability and security. -- Archive nodes should also continue to execute to ensure finalized blocks are in the database and can be migrated, preserving the integrity and accessibility of the network's history. - -### Block Producers and SNARK Workers -1. It is crucial for the network's successful upgrade that all block producers and SNARK workers maintain their block-producing nodes up and running throughout the state finalization phase. -2. If you are running multiple daemons like is common with many operators, you can run one single node at this stage. -3. If you are a Delegation Program operator, remember that your uptime data will continue to be tracked during the state finalization phase and will be considered for the delegation grant in the following epoch. - -### Archive Node Operators and Rosetta Operators -**If you plan to do the _trustful_ migration, you can skip this step.** -If you are doing the trustless migration, then: -1. Continue to execute the archive node to ensure finalized blocks are in the database and can be migrated. -2. Continue to run incremental archive node migrations until after the network stops at the stop-network slot. -3. For more information on the archive node migration process, please refer to the [Archive Migration](/berkeley-upgrade/archive-migration) section - -### Exchanges - -Exchanges shall disable MINA deposits and withdrawals during the state finalization period (the period between _stop-transaction-slot_ and _stop-network-slot_) since any transactions after the _stop-transaction-slot_ will not be part of the upgraded chain. - -Remember that although you might be able to submit transactions, the majority of the block producers will be running a node that discards any blocks with transactions. - -*** - -## Upgrade - -- Starting at the _stop-network-slot_ the network will not produce nor accept new blocks, resulting in halting the network. During the upgrade period, o1Labs will use automated tooling to export the network state based on the block at the slot just before the _stop-transaction-slot_. The exported state will then be baked into the new Berkeley build, which will be used to initiate the upgraded network. It is during the upgrade windows that the Berkeley network infrastructure will be bootstrapped, and seed nodes will become available. o1Labs will also finalize the archive node migration and publish the PostgreSQL database dumps for import by the archive node operators who wish to bootstrap their archives in a trustful manner. -- There is a tool available to validate that the Berkeley node was built from the pre-upgrade network state. To validate, follow the instructions provided in this [location](https://github.com/MinaProtocol/mina/blob/berkeley/docs/upgrading-to-berkeley.md) - -### Block Producers and SNARK Workers -1. During the upgrade phase (between _stop-network-slot_ and the publishing of the Berkeley release), block producers can shut down their nodes. -2. After the publication of the Berkeley node release, block producers and SNARK workers should upgrade their nodes and be prepared for block production at the genesis timestamp, which is the slot when the first Berkeley block will be produced. -3. It is possible to continue using the same libp2p key after the upgrade. Remember to adjust the new flag to pass the libp2p key to the node. - -### Archive Node Operators and Rosetta Operators -1. Upon publishing the archive node Berkeley release, archive node operators and Rosetta operators should upgrade their systems. -There will be both Docker images and archive node releases available to choose from. -2. Depending on the chosen migration method: - - _Trustless_ - - Operators should direct their Berkeley archive process to the previously migrated database. - - _Trustful_ - - Operators shall import the SQL dump file provided by o1Labs to a freshly created database. - - Operators should direct their Berkeley archive process to the newly created database. - -**Please note:** both the _trustless_ and _trustful_ migration processes will discard all Mainnet blocks that are not canonical. If you wish to preserve the entire block history, i.e. including non-canonical blocks, you should maintain the Mainnet archive node database for posterior querying needs. - -### Exchanges -1. Exchanges shall disable MINA deposits and withdrawals during the entirety of the upgrade downtime, since the _stop-transaction-slot_ until the Mainnet Berkeley network is operational. -2. After the Berkeley releases are published, exchanges should upgrade their nodes and prepare for the new network to start block production. - -*** - -## Post-Upgrade -- At approximately 1 hour after the publishing of the Berkeley node release, at a predefined slot (Berkeley genesis timestamp), block production will start, and the network is successfully upgraded. -- Node operators can monitor their nodes and provide feedback to the technical team in case of any issues. Builders can start deploying zkApps. -- **Please note:** The Node Status service will not be enabled by default in the Berkeley release. If you wish to provide Node Status and Error metrics and reports to Mina Foundation, helping monitor the network in the initial phase, please use the following flags when running your nodes: - - `--node-stats-type [full|simple]` - - `--node-status-url https://nodestats.minaprotocol.com/submit/stats` - - `--node-error-url https://nodestats.minaprotocol.com/submit/stats` - - The error collection service tries to report any node crashes before the node process is terminated - -### Block Producers and SNARK Workers -1. Ensure that all systems have been upgraded and prepared for the start of block production. -2. Monitor nodes and network health, and provide feedback to the engineering team in case of any issues. - -### Archive Node Operators and Rosetta Operators -1. Ensure that all systems have been upgraded and prepared for the start of block production. -2. Monitor nodes and network health, and provide feedback to the engineering team in case of any issues. - -### Exchange and Builders -1. After the predefined Berkeley genesis timestamp, block production will commence, and MINA deposits and withdrawals can be resumed. -2. Ensure that all systems have been upgraded and prepared for the start of block production. -3. Monitor nodes and network health, and provide feedback to the engineering team in case of any issues. diff --git a/docs/exchange-operators/rosetta/run-with-docker.mdx b/docs/exchange-operators/rosetta/run-with-docker.mdx index f8e4b2a51..6ea7213bd 100644 --- a/docs/exchange-operators/rosetta/run-with-docker.mdx +++ b/docs/exchange-operators/rosetta/run-with-docker.mdx @@ -46,7 +46,7 @@ Run the container with following command (replace the image tag with one from do docker run -it --rm --name rosetta \ --entrypoint=./docker-start.sh \ -p 10101:10101 -p 3085:3085 -p 3086:3086 -p 3087:3087 \ - minaprotocol/mina-rosetta:2.0.0-039296a-focal + minaprotocol/mina-rosetta:2.0.0-039296a-focal **<_CHANGE_ME_>** You can also create a file with the environment variables and pass it to the docker run command with `--env-file` flag. For example, create a file named `mainnet.env` with the following content: diff --git a/docs/mina-protocol/sending-a-payment.mdx b/docs/mina-protocol/sending-a-payment.mdx index c766b7655..95cea9e45 100644 --- a/docs/mina-protocol/sending-a-payment.mdx +++ b/docs/mina-protocol/sending-a-payment.mdx @@ -167,19 +167,19 @@ Once you feel comfortable with the basics of creating an address, and sending & Sometimes you may wish to send many transactions: for example, to payout rewards to those delegating to you if you're running a staking pool. -All information here is relevant as of the 2.0.0 build: +All information here is relevant as of the 3.0.0 build: ### Rate limiting -Currently, nodes on the network will rate limit receiving messages from a given node. As of the 2.0.0 build, your node will also follow this rate limit when sending transactions. Specifically, the limit is currently set at 10 transactions every 15 seconds computed over a 5 minute window. If you attempt to send transactions faster than this rate, your node will queue them up and flush them as older transactions expire from the window upon which the rate limit is computed. You do not need to throttle sending these transactions yourself. +Currently, nodes on the network will rate limit receiving messages from a given node. As of the 3.0.0 build, your node will also follow this rate limit when sending transactions. Specifically, the limit is currently set at 10 transactions every 15 seconds computed over a 5 minute window. If you attempt to send transactions faster than this rate, your node will queue them up and flush them as older transactions expire from the window upon which the rate limit is computed. You do not need to throttle sending these transactions yourself. Note that older releases of the mina daemon do not perform this rate limiting; if you are running an older version, you should manually limit the number of transactions. Due to overheads from rebroadcasting transactions, we do not recommend sending more than 50 transactions every 5 minutes if you need to manually rate limit. ### My node crashed or disconnected before I could finish sending transactions -The Mina daemon does _not_ currently persist the transaction pool. This means that the transactions that your node will be unaware of any transactions that you've sent so far if your node crashes in the middle of this process. As of the 2.0.0 build, you can resend all transactions (exactly in the same manner as before) and they will be rebroadcasted on the network. +The Mina daemon does _not_ currently persist the transaction pool. This means that the transactions that your node will be unaware of any transactions that you've sent so far if your node crashes in the middle of this process. As of the 3.0.0 build, you can resend all transactions (exactly in the same manner as before) and they will be rebroadcasted on the network. -If you believe you were temporarily disconnected from the network, but your node stayed online (i.e. the gossip network may have missed one or more of your transactions), as of the 2.0.0 build, you can resend any of the transactions locally and they will be broadcasted again to the network even if your node thinks they've already been shared. +If you believe you were temporarily disconnected from the network, but your node stayed online (i.e. the gossip network may have missed one or more of your transactions), as of the 3.0.0 build, you can resend any of the transactions locally and they will be broadcasted again to the network even if your node thinks they've already been shared. ### Cancelling a transaction and setting a new fee diff --git a/docs/node-developers/sandbox-node.mdx b/docs/node-developers/sandbox-node.mdx index 50506ada0..65f3f93ab 100644 --- a/docs/node-developers/sandbox-node.mdx +++ b/docs/node-developers/sandbox-node.mdx @@ -26,7 +26,7 @@ docker run \ --name mina \ -e RUN_DEMO=true \ -e MINA_PRIVKEY_PASS='' \ - minaprotocol/mina-daemon:2.0.0-039296a-bullseye-mainnet + minaprotocol/mina-daemon:2.0.0-039296a-bullseye-mainnet **<_CHANGE_ME_>** ``` diff --git a/docs/node-operators/archive-node/getting-started.mdx b/docs/node-operators/archive-node/getting-started.mdx index a55d1ddb7..7ff28e982 100644 --- a/docs/node-operators/archive-node/getting-started.mdx +++ b/docs/node-operators/archive-node/getting-started.mdx @@ -55,13 +55,13 @@ Running an archive node requires some knowledge of managing a PostgreSQL databas - Ubuntu/Debian: ``` - sudo apt-get install mina-archive=2.0.0-039296a + sudo apt-get install mina-archive=2.0.0-039296a **<_CHANGE_ME_>** ``` - Docker: ``` - minaprotocol/mina-archive:2.0.0-039296a-bullseye + minaprotocol/mina-archive:2.0.0-039296a-bullseye **<_CHANGE_ME_>** ``` ## Set up the archive node @@ -93,7 +93,7 @@ To run a local archive node to run it in the foreground for testing: 1. Load the mina archive schema into the archive database, (create_schema.sql and zkapp_tables.sql): ```sh - psql -h localhost -p 5432 -d archive -f <(curl -Ls https://raw.githubusercontent.com/MinaProtocol/mina/release/2.0.0/src/app/archive/create_schema.sql) + psql -h localhost -p 5432 -d archive -f <(curl -Ls https://raw.githubusercontent.com/MinaProtocol/mina/release/3.0.0/src/app/archive/create_schema.sql) ``` @@ -125,7 +125,7 @@ To get started with installing and running the archive node using Docker, follow 2. Pull the archive node image from Docker Hub. ```sh - docker pull minaprotocol/mina-archive:2.0.0-039296a-bullseye + docker pull minaprotocol/mina-archive:2.0.0-039296a-bullseye **<_CHANGE_ME_>** ``` 3. Pull and install the postgres image from Docker Hub. @@ -168,7 +168,7 @@ To get started with installing and running the archive node using Docker, follow --name archive \ -p 3086:3086 \ -v /tmp/archive:/data \ - minaprotocol/mina-archive:2.0.0-039296a-bullseye \ + minaprotocol/mina-archive:2.0.0-039296a-bullseye \ **<_CHANGE_ME_>** mina-archive run \ --postgres-uri postgres://postgres:postgres@postgres:5432/archive \ --server-port 3086 @@ -177,9 +177,9 @@ To get started with installing and running the archive node using Docker, follow :::warning -Please be careful when using `--config` argument at archive node bootstrap. +Please be careful when using `--config` argument at archive node bootstrap. -It should be provided only when archive node is connected to +It should be provided only when archive node is connected to short lived network created mainly for testing, local development or experimental networks. *Never* use it on long lived network such as mainnet or devnet @@ -212,7 +212,7 @@ To run the archive node using Docker Compose: 3. Pull the archive node image from Docker Hub. ```sh - docker pull minaprotocol/mina-archive:2.0.0-039296a-bullseye + docker pull minaprotocol/mina-archive:2.0.0-039296a-bullseye **<_CHANGE_ME_>** ``` 4. Pull and install the postgres image from Docker Hub. @@ -240,7 +240,7 @@ To run the archive node using Docker Compose: ports: - '5432:5432' archive: - image: 'minaprotocol/mina-archive:2.0.0-039296a-bullseye' + image: 'minaprotocol/mina-archive:2.0.0-039296a-bullseye' **<_CHANGE_ME_>** command: >- mina-archive run --postgres-uri postgres://postgres:postgres@postgres:5432/archive --server-port 3086 diff --git a/docs/node-operators/block-producer-node/connecting-to-the-network.mdx b/docs/node-operators/block-producer-node/connecting-to-the-network.mdx index c48693a47..22dc467a3 100644 --- a/docs/node-operators/block-producer-node/connecting-to-the-network.mdx +++ b/docs/node-operators/block-producer-node/connecting-to-the-network.mdx @@ -34,7 +34,7 @@ The first step to connecting to Mainnet is to install the latest daemon version. ### Ubuntu 20.04 and Debian 10, 11, 12 -To install the latest [Mainnet **Stable** Release 2.0.0](https://github.com/MinaProtocol/mina/releases/tag/2.0.0), use the [Installation](/node-operators/block-producer-node/getting-started#installation) steps for your environment. +To install the latest [Mainnet **Stable** Release 3.0.0](https://github.com/MinaProtocol/mina/releases/tag/3.0.0), use the [Installation](/node-operators/block-producer-node/getting-started#installation) steps for your environment. ## Start a standalone mina node @@ -179,7 +179,7 @@ docker run --name mina -d \ --mount "type=bind,source=$(pwd)/.mina-env,dst=/entrypoint.d/mina-env,readonly" \ --mount "type=bind,source=$(pwd)/keys,dst=/keys,readonly" \ --mount "type=bind,source=$(pwd)/.mina-config,dst=/root/.mina-config" \ -minaprotocol/mina-daemon:2.0.0-039296a-bullseye-mainnet \ +minaprotocol/mina-daemon:2.0.0-039296a-bullseye-mainnet \ **<_CHANGE_ME_>** daemon ``` diff --git a/docs/node-operators/block-producer-node/getting-started.mdx b/docs/node-operators/block-producer-node/getting-started.mdx index 0a714d6c5..3f95ea560 100644 --- a/docs/node-operators/block-producer-node/getting-started.mdx +++ b/docs/node-operators/block-producer-node/getting-started.mdx @@ -58,7 +58,7 @@ o1Labs has tested running nodes on several cloud providers. We recommend the fol ## Installation -To install the latest [Mainnet **Stable** Release 2.0.0](https://github.com/MinaProtocol/mina/releases/tag/2.0.0), use the installation steps for your environment. Supported environments include macOS, Linux (Debian 10, 11 and Ubuntu 20.04 LTS), and any host machine with Docker. +To install the latest [Mainnet **Stable** Release 3.0.0](https://github.com/MinaProtocol/mina/releases/tag/3.0.0), use the installation steps for your environment. Supported environments include macOS, Linux (Debian 10, 11 and Ubuntu 20.04 LTS), and any host machine with Docker. The binary download is around 1 GB, so the installation might take a few minutes. @@ -79,7 +79,7 @@ sudo apt-get update Now install the node package. ``` -sudo apt-get install -y curl unzip mina-mainnet=2.0.0-039296a +sudo apt-get install -y curl unzip mina-mainnet=2.0.0-039296a **<_CHANGE_ME_>** ``` diff --git a/docs/berkeley-upgrade/flags-configs.mdx b/docs/node-operators/flags-configs.mdx similarity index 92% rename from docs/berkeley-upgrade/flags-configs.mdx rename to docs/node-operators/flags-configs.mdx index 878a8e71a..42ffb3a86 100644 --- a/docs/berkeley-upgrade/flags-configs.mdx +++ b/docs/node-operators/flags-configs.mdx @@ -12,22 +12,22 @@ keywords: # Post-Upgrade Flags and Configurations for Mainnet -Please refer to the Berkeley node release notes [here](https://github.com/MinaProtocol/mina/releases/tag/2.0.0). +Please refer to the Berkeley node release notes [here](https://github.com/MinaProtocol/mina/releases/tag/3.0.0). ### Network details ``` Chain ID -5f704cc0c82e0ed70e873f0893d7e06f148524e3f0bdae2afb02e7819a0c24d1 +5f704cc0c82e0ed70e873f0893d7e06f148524e3f0bdae2afb02e7819a0c24d1 **<_CHANGE_ME_>** Git SHA-1 -039296a260080ed02d0d0750d185921f030b6c9c +039296a260080ed02d0d0750d185921f030b6c9c **<_CHANGE_ME_>** Seed List https://bootnodes.minaprotocol.com/networks/mainnet.txt Node build -https://github.com/MinaProtocol/mina/releases/tag/2.0.0 +https://github.com/MinaProtocol/mina/releases/tag/3.0.0 ``` ### Block Producer​s @@ -87,8 +87,8 @@ Running an Archive Node involves setting up a non-block-producing node and a Pos For more information about running archive nodes, see [Archive Node](/node-operators/archive-node). The PostgreSQL database requires two schemas: -1. The PostgreSQL schema used by the Mina archive database: in the [release notes](https://github.com/MinaProtocol/mina/releases/tag/2.0.0) -2. The PostgreSQL schema extensions to support zkApp commands: in the [release notes](https://github.com/MinaProtocol/mina/releases/tag/2.0.0) +1. The PostgreSQL schema used by the Mina archive database: in the [release notes](https://github.com/MinaProtocol/mina/releases/tag/3.0.0) +2. The PostgreSQL schema extensions to support zkApp commands: in the [release notes](https://github.com/MinaProtocol/mina/releases/tag/3.0.0) The non-block-producing node must be configured with the following flags: ``` @@ -127,7 +127,7 @@ docker run --name rosetta --rm \ -p 3088:3088 \ --entrypoint '' \ -gcr.io/o1labs-192920/mina-rosetta: \ +gcr.io/o1labs-192920/mina-rosetta: **<_CHANGE_ME_>** \ /usr/local/bin/mina-rosetta \ --archive-uri "${PG_CONNECTION_STRING}" \ --graphql-uri "${GRAPHQL_URL}" \ diff --git a/docs/node-operators/generating-a-keypair.mdx b/docs/node-operators/generating-a-keypair.mdx index 6f3224bd4..5ca9f90b3 100644 --- a/docs/node-operators/generating-a-keypair.mdx +++ b/docs/node-operators/generating-a-keypair.mdx @@ -74,7 +74,7 @@ Generate a new public, private keypair ```sh echo "deb [trusted=yes] http://packages.o1test.net $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/mina.list sudo apt-get update - sudo apt-get install -y mina-mainnet=2.0.0-039296a + sudo apt-get install -y mina-mainnet=2.0.0-039296a **<_CHANGE_ME_>** ``` 1. Verify that the key generation tool installed correctly: @@ -129,7 +129,7 @@ Make sure to set a new and secure password for the following commands. Mina will cd ~ docker run -it --rm --entrypoint "" \ --volume $(pwd)/keys:/keys \ - minaprotocol/mina-daemon:2.0.0-039296a-bullseye-mainnet \ + minaprotocol/mina-daemon:2.0.0-039296a-bullseye-mainnet \ **<_CHANGE_ME_>** mina advanced generate-keypair --privkey-path /keys/my-wallet ``` @@ -163,7 +163,7 @@ On Docker: ``` docker run -it --rm --entrypoint "" \ --volume $(pwd)/keys:/keys \ - minaprotocol/mina-daemon:2.0.0-039296a-bullseye-mainnet \ + minaprotocol/mina-daemon:2.0.0-039296a-bullseye-mainnet \ **<_CHANGE_ME_>** mina advanced validate-keypair --privkey-path /keys/my-wallet ``` diff --git a/docs/node-operators/mina-signer.mdx b/docs/node-operators/mina-signer.mdx index 6ab811ccc..ddebcce98 100644 --- a/docs/node-operators/mina-signer.mdx +++ b/docs/node-operators/mina-signer.mdx @@ -13,3 +13,74 @@ keywords: The Mina Signer is a NodeJS SDK which allows you to sign strings, payments, and delegations using Mina's key pairs for various specified networks. See the [Mina Signer](https://github.com/o1-labs/o1js/tree/main/src/mina-signer) repository for installation and usage instructions. + + +## Migration from o1labs/client-sdk to mina-signer + +The signing library `o1labs/client-sdk` was deprecated some time ago and will stop working after the Mina mainnet upgrade. All users should upgrade to use the [mina-signer](https://www.npmjs.com/package/mina-signer) library. + +Below you will find an example of how to use the `mina-signer` library. Please keep in mind the following: + +1. Make sure to adjust the `nonce` to the correct nonce on the account you want to use as "sender" +1. Update the `url` variable with an existing Mina Node GraphQL endpoint + +```javascript +import { Client } from 'mina-signer'; + +// create the client and define the keypair + +const client = new Client({ network: 'testnet' }); // Mind the `network` client configuration option + +const senderPrivateKey = 'EKFd1Gx...'; // Sender's private key +const senderPublicKey = 'B62qrDM...'; // Sender's public key, perhaps derived from the private key using `client.derivePublicKey(senderPrivateKey)`; + +// define and sign payment + +let payment = { + from: senderPublicKey, + to: 'B62qkBw...', // Recipient public key + amount: 100, + nonce: 1, + fee: 1000000, +}; + +const signedPayment = client.signPayment(payment, senderPrivateKey); + +// send payment to graphql endpoint + +const url = 'https://qanet.minaprotocol.network/graphql'; + +const sendPaymentMutationQuery = ` +mutation SendPayment($input: SendPaymentInput!, $signature: SignatureInput!) { + sendPayment(input: $input, signature: $signature) { + payment { + hash + } + } +} +`; +const graphQlVariables = { + input: signedPayment.data, + signature: signedPayment.signature, +}; +const body = JSON.stringify({ + query: sendPaymentMutationQuery, + variables: graphQlVariables, + operationName: 'SendPayment', +}); + +const paymentResponse = await fetch(url, { + method: 'POST', + headers: { 'Content-Type': 'application/json' }, + body +}); + +const paymentResponseJson = await paymentResponse.json(); +if (paymentResponse.ok) { + console.log(`Transaction hash: ${paymentResponseJson.data.sendPayment.payment.hash}`); +} else { + console.error(JSON.stringify(paymentResponseJson)); +} + + +``` diff --git a/docs/berkeley-upgrade/requirements.mdx b/docs/node-operators/requirements.mdx similarity index 100% rename from docs/berkeley-upgrade/requirements.mdx rename to docs/node-operators/requirements.mdx diff --git a/docs/node-operators/seed-peers/getting-started.mdx b/docs/node-operators/seed-peers/getting-started.mdx index d7c702ff2..46cad9c4f 100644 --- a/docs/node-operators/seed-peers/getting-started.mdx +++ b/docs/node-operators/seed-peers/getting-started.mdx @@ -88,7 +88,7 @@ docker run --name mina-seed-node -d \ -v "$(pwd)/keys:/root/keys:ro" \ -v "$(pwd)/.mina-config:/root/.mina-config" \ -v "$(pwd)/.mina-env:/entrypoint.d/mina-env:ro" \ -minaprotocol/mina-daemon:2.0.0-039296a-bullseye-mainnet \ +minaprotocol/mina-daemon:2.0.0-039296a-bullseye-mainnet \ **<_CHANGE_ME_>** daemon ``` diff --git a/docs/welcome.mdx b/docs/welcome.mdx index ed697d7f9..4be98db3d 100644 --- a/docs/welcome.mdx +++ b/docs/welcome.mdx @@ -1,33 +1,20 @@ --- id: welcome -title: "Important: Mainnet Upgrade" +title: "Welcome" description: Mina is building a gateway between the real world and crypto — and the infrastructure for the secure, democratic future we all deserve. slug: / --- import HomepageFeatures from "@site/src/components/features/HomepageFeatures"; -# Mainnet (Berkeley) Major Upgrade +# Welcome -:::caution May 21st 2024 +:::caution Berkeley Release has landed -Please make sure to upgrade your mina nodes to **2.0.0** +Please make sure to upgrade your mina nodes to **3.0.0** ([Release notes](https://github.com/MinaProtocol/mina/discussions/15662) **<_CHANGE_ME_>**) -=> [Release notes](https://github.com/MinaProtocol/mina/discussions/15662) +[See instructions to upgrade your Mina node](/node-operators/requirements) ::: -After a series of private and public testing rounds, the Mina Protocol developers and community are confident in the software and processes that will upgrade the Mina Protocol Mainnet network. - -This [Berkeley Upgrade section](/berkeley-upgrade/requirements) describes the upgrade processes and operations for the different node types. Please refer to [Mina’s Discord channels](https://discord.gg/minaprotocol) for further support. - -### Mainnet Upgrade Timeline - - - -### Feedback and Questions​ -Thank you for participating in the Berkeley upgrade. - -If you have any questions or feedback related to the Berkeley upgrade, please use the dedicated Discord [#mainnet-updates](https://discord.com/channels/484437221055922177/816099272859844638) channel. - -### Next: [How to upgrade your Mina node](/berkeley-upgrade/requirements) + diff --git a/docusaurus.config.js b/docusaurus.config.js index 3765c23e1..ac642912c 100644 --- a/docusaurus.config.js +++ b/docusaurus.config.js @@ -28,10 +28,6 @@ module.exports = { '@docusaurus/plugin-client-redirects', { redirects: [ - { - from: '/berkeley-upgrade', - to: '/berkeley-upgrade/requirements', - }, { from: '/node-operators/scan-state', to: '/mina-protocol/scan-state', diff --git a/sidebars.js b/sidebars.js index 85a5e449a..d251fcbeb 100644 --- a/sidebars.js +++ b/sidebars.js @@ -1,34 +1,6 @@ module.exports = { docs: [ 'welcome', - { - type: 'category', - label: 'Berkeley Upgrade', - items: [ - 'berkeley-upgrade/requirements', - { - type: 'category', - label: 'Archive Migration', - link: { - type: 'doc', - id: 'berkeley-upgrade/archive-migration/index', - }, - items: [ - 'berkeley-upgrade/archive-migration/understanding-archive-migration', - 'berkeley-upgrade/archive-migration/archive-migration-prerequisites', - 'berkeley-upgrade/archive-migration/archive-migration-installation', - 'berkeley-upgrade/archive-migration/migrating-archive-database-to-berkeley', - 'berkeley-upgrade/archive-migration/mainnet-database-maintenance', - 'berkeley-upgrade/archive-migration/debian-example', - 'berkeley-upgrade/archive-migration/docker-example', - 'berkeley-upgrade/archive-migration/appendix', - ], - }, - 'berkeley-upgrade/upgrade-steps', - 'berkeley-upgrade/flags-configs', - 'berkeley-upgrade/appendix', - ], - }, { type: 'category', label: 'About Mina', @@ -1296,7 +1268,7 @@ module.exports = { id: 'node-operators/index', }, items: [ - 'node-operators/staking-and-snarking', + 'node-operators/requirements', 'node-operators/generating-a-keypair', { type: 'category', @@ -1376,6 +1348,7 @@ module.exports = { 'node-operators/delegation-program/uptime-tracking-system', ], }, + 'node-operators/staking-and-snarking', 'node-operators/staking-service-guidelines', 'node-operators/mina-signer', 'node-operators/mina-cli-reference', diff --git a/src/components/features/HomepageFeatures.tsx b/src/components/features/HomepageFeatures.tsx index 328e8d987..409af0062 100644 --- a/src/components/features/HomepageFeatures.tsx +++ b/src/components/features/HomepageFeatures.tsx @@ -95,7 +95,7 @@ const FeatureList: FeatureItem[] = [ title: 'Run a Node', image: '/svg/homepage/node_operators.svg', buttonText: 'Node Operators', - buttonLink: '/node-operators/getting-started', + buttonLink: '/node-operators', description: ( <> From 644cf737c9f4225547f9f43b781f13e269990365 Mon Sep 17 00:00:00 2001 From: David Lehuby Date: Fri, 31 May 2024 16:58:02 +1000 Subject: [PATCH 02/12] Remove node 'zkApp programmability is not yet available' --- docs/zkapps/advanced/experimental.mdx | 14 +-- .../zkapps-for-ethereum-developers.mdx | 8 +- docs/zkapps/faq.mdx | 8 +- docs/zkapps/o1js/basic-concepts.md | 6 - docs/zkapps/o1js/bitwise-operations.mdx | 6 - docs/zkapps/o1js/custom-tokens.mdx | 6 - docs/zkapps/o1js/ecdsa.mdx | 6 - docs/zkapps/o1js/foreign-fields.mdx | 6 - docs/zkapps/o1js/gadgets.mdx | 6 - docs/zkapps/o1js/index.mdx | 6 - docs/zkapps/o1js/keccak.mdx | 6 - docs/zkapps/o1js/merkle-tree.mdx | 10 +- docs/zkapps/o1js/recursion.mdx | 6 - docs/zkapps/o1js/sha256.mdx | 8 +- docs/zkapps/roadmap.mdx | 9 +- docs/zkapps/tutorials/01-hello-world.mdx | 6 - .../02-private-inputs-hash-functions.mdx | 30 ++--- .../tutorials/03-deploying-to-a-network.mdx | 60 +++++----- .../tutorials/04-zkapp-ui-with-react.mdx | 46 ++++--- .../05-common-types-and-functions.mdx | 10 +- docs/zkapps/tutorials/06-offchain-storage.mdx | 42 +++---- docs/zkapps/tutorials/07-oracle.mdx | 14 +-- docs/zkapps/tutorials/08-custom-tokens.mdx | 18 +-- docs/zkapps/tutorials/09-recursion.mdx | 6 - docs/zkapps/tutorials/10-account-updates.mdx | 6 - .../tutorials/11-advanced-account-updates.mdx | 6 - .../tutorials/anonymous-message-board.mdx | 57 ++++----- docs/zkapps/tutorials/index.mdx | 6 - .../interacting-with-zkapps-server-side.mdx | 6 - .../feature-overview/actions-and-reducer.mdx | 14 +-- .../feature-overview/custom-tokens.mdx | 23 ++-- .../feature-overview/events.mdx | 9 +- .../fetch-events-and-actions.mdx | 10 +- .../feature-overview/offchain-storage.mdx | 10 +- .../feature-overview/on-chain-values.mdx | 6 - .../feature-overview/permissions.mdx | 22 ++-- .../feature-overview/time-locked-accounts.mdx | 22 ++-- docs/zkapps/writing-a-zkapp/index.mdx | 8 +- .../getting-started-zkapps.mdx | 48 ++++---- .../how-to-deploy-a-zkapp.mdx | 14 +-- .../how-to-write-a-zkapp-ui.mdx | 42 +++---- .../how-to-write-a-zkapp.mdx | 112 +++++++++--------- .../how-zkapps-work.mdx | 28 ++--- .../install-zkapp-cli.mdx | 12 +- .../interact-with-mina.md | 6 - .../introduction-to-zkapps/secure-zkapps.mdx | 6 - .../smart-contracts.mdx | 30 ++--- .../testing-zkapps-lightnet.mdx | 56 ++++----- .../testing-zkapps-locally.mdx | 8 +- 49 files changed, 306 insertions(+), 604 deletions(-) diff --git a/docs/zkapps/advanced/experimental.mdx b/docs/zkapps/advanced/experimental.mdx index c7334aa93..82e54271a 100644 --- a/docs/zkapps/advanced/experimental.mdx +++ b/docs/zkapps/advanced/experimental.mdx @@ -1,20 +1,14 @@ --- title: Experimental features -description: Experimental features are not considered production-ready. +description: Experimental features are not considered production-ready. keywords: - experimental - feedback --- -:::info - -zkApp programmability is not yet available on the Mina **Mainnet**, but zkApps can now be deployed on the Mina **Devnet**. - -::: - # Experimental features -Some new features are considered experimental before they are production-ready. +Some new features are considered experimental before they are production-ready. :::experimental @@ -28,9 +22,9 @@ In return, your feedback helps us make sure that our new features are reliable a ## Feedback -We appreciate any and all feedback you want to provide. +We appreciate any and all feedback you want to provide. -The best place to provide feedback and ask questions is on [Mina Protocol Discord](https://bit.ly/MinaDiscord). +The best place to provide feedback and ask questions is on [Mina Protocol Discord](https://bit.ly/MinaDiscord). To ask zkApps questions and engage with other developers building zkApps with o1js, use the [#zkapps-developers](https://discord.com/channels/484437221055922177/915745847692636181) channel. diff --git a/docs/zkapps/advanced/zkapps-for-ethereum-developers.mdx b/docs/zkapps/advanced/zkapps-for-ethereum-developers.mdx index f24b99ba6..37fcd7208 100644 --- a/docs/zkapps/advanced/zkapps-for-ethereum-developers.mdx +++ b/docs/zkapps/advanced/zkapps-for-ethereum-developers.mdx @@ -15,12 +15,6 @@ keywords: - decentralization --- -:::info - -zkApp programmability is not yet available on the Mina **Mainnet**, but zkApps can now be deployed on the Mina **Devnet**. - -::: - # zkApps for Ethereum Developers Mina and Ethereum are both decentralized, programmable, layer-one blockchains, @@ -134,4 +128,4 @@ The Nil Foundation is working on the [first of these bridges](https://verify.min ### Have another question? -Reach out in the [#zkapps-developers](https://discord.com/channels/484437221055922177/915745847692636181) channel on Mina Protocol Discord. It's better when we learn together. +Reach out in the [#zkapps-developers](https://discord.com/channels/484437221055922177/915745847692636181) channel on Mina Protocol Discord. It's better when we learn together. diff --git a/docs/zkapps/faq.mdx b/docs/zkapps/faq.mdx index bc70239e3..b99d7d38c 100644 --- a/docs/zkapps/faq.mdx +++ b/docs/zkapps/faq.mdx @@ -10,12 +10,6 @@ keywords: - o1js --- -:::info - -zkApp programmability is not yet available on the Mina **Mainnet**, but zkApps can now be deployed on the Mina **Devnet**. - -::: - # zkApps and o1js FAQ Answers to common questions about zkApps (zero knowledge apps) and o1js, a TypeScript library for writing zk smart contracts. @@ -148,7 +142,7 @@ Use the `requireSignature` command. See the [requireSignature](/zkapps/o1js-refe ### How do I configure who has the authority to interact and make changes to a specific part of an account? -Permissions determine who has the authority to interact and make changes to a specific part of a smart contract. See [Permissions](https://docs.minaprotocol.com/zkapps/writing-a-zkapp/feature-overview/permissions). +Permissions determine who has the authority to interact and make changes to a specific part of a smart contract. See [Permissions](https://docs.minaprotocol.com/zkapps/writing-a-zkapp/feature-overview/permissions). ### How are proofs generated in the Mina Protocol? diff --git a/docs/zkapps/o1js/basic-concepts.md b/docs/zkapps/o1js/basic-concepts.md index ee2501828..25d34efd4 100644 --- a/docs/zkapps/o1js/basic-concepts.md +++ b/docs/zkapps/o1js/basic-concepts.md @@ -19,12 +19,6 @@ keywords: - methods --- -:::info - -zkApp programmability is not yet available on the Mina **Mainnet**, but zkApps can now be deployed on the Mina **Devnet**. - -::: - # o1js Basic Concepts o1js is a TypeScript (TS) library for writing general-purpose zero knowledge (zk) programs and writing zk smart contracts for Mina. diff --git a/docs/zkapps/o1js/bitwise-operations.mdx b/docs/zkapps/o1js/bitwise-operations.mdx index 24de82b6c..c7f7e35d3 100644 --- a/docs/zkapps/o1js/bitwise-operations.mdx +++ b/docs/zkapps/o1js/bitwise-operations.mdx @@ -8,12 +8,6 @@ keywords: - o1js --- -:::info - -zkApp programmability is not yet available on the Mina **Mainnet**, but zkApps can now be deployed on the Mina **Devnet**. - -::: - # Bitwise Operations Bitwise operations manipulate individual bits within a binary representation of a number. They can, at times, resemble boolean operations but apply to a sequence of bits instead of booleans. Bitwise operations are generally available in most programming languages, including TypeScript. o1js provides versions of them that operate on `Field` elements and result in the necessary circuit constraints to generate a zero knowledge proof of the computation. This is especially useful when implementing hashing algorithms such as SHA256. diff --git a/docs/zkapps/o1js/custom-tokens.mdx b/docs/zkapps/o1js/custom-tokens.mdx index 1d36d909e..04049ce6f 100644 --- a/docs/zkapps/o1js/custom-tokens.mdx +++ b/docs/zkapps/o1js/custom-tokens.mdx @@ -15,12 +15,6 @@ keywords: - zkApps updates --- -:::info - -zkApp programmability is not yet available on the Mina **Mainnet**, but zkApps can now be deployed on the Mina **Devnet**. - -::: - # Custom Token API You can use o1js to perform common token operations, such as minting, burning, and sending tokens. diff --git a/docs/zkapps/o1js/ecdsa.mdx b/docs/zkapps/o1js/ecdsa.mdx index e3f75cce1..e30a6da5a 100644 --- a/docs/zkapps/o1js/ecdsa.mdx +++ b/docs/zkapps/o1js/ecdsa.mdx @@ -13,12 +13,6 @@ keywords: - blockchain --- -:::info - -zkApp programmability is not yet available on the Mina **Mainnet**, but zkApps can now be deployed on the Mina **Devnet**. - -::: - # ECDSA ECDSA, or Elliptic Curve Digital Signature Algorithm, is a cryptographic algorithm used to sign and verify messages. It is used in many blockchains, including Ethereum, to sign transactions. diff --git a/docs/zkapps/o1js/foreign-fields.mdx b/docs/zkapps/o1js/foreign-fields.mdx index 015de2a86..b9b6589fa 100644 --- a/docs/zkapps/o1js/foreign-fields.mdx +++ b/docs/zkapps/o1js/foreign-fields.mdx @@ -10,12 +10,6 @@ keywords: - o1js --- -:::info - -zkApp programmability is not yet available on the Mina **Mainnet**, but zkApps can now be deployed on the Mina **Devnet**. - -::: - # Foreign Field Arithmetic A foreign field is a [finite field](https://en.wikipedia.org/wiki/Modular_arithmetic) different from the native field of the proof system. o1js exposes operations like modular addition and multiplication that work in any finite field of size less than `2^259`. diff --git a/docs/zkapps/o1js/gadgets.mdx b/docs/zkapps/o1js/gadgets.mdx index 0c925e02a..0afb26a54 100644 --- a/docs/zkapps/o1js/gadgets.mdx +++ b/docs/zkapps/o1js/gadgets.mdx @@ -11,12 +11,6 @@ keywords: - blockchain --- -:::info - -zkApp programmability is not yet available on the Mina **Mainnet**, but zkApps can now be deployed on the Mina **Devnet**. - -::: - # Gadgets Gadgets are small, reusable low-level building blocks that simplify the process of creating new cryptographic primitives. Most gadgets build upon custom gates and act as low-level accelerators in the proof system. diff --git a/docs/zkapps/o1js/index.mdx b/docs/zkapps/o1js/index.mdx index 1d6e18428..cb60398e1 100644 --- a/docs/zkapps/o1js/index.mdx +++ b/docs/zkapps/o1js/index.mdx @@ -18,12 +18,6 @@ keywords: - typescript library --- -:::info - -zkApp programmability is not yet available on the Mina **Mainnet**, but zkApps can now be deployed on the Mina **Devnet**. - -::: - # Introduction to o1js o1js is a TypeScript library for: diff --git a/docs/zkapps/o1js/keccak.mdx b/docs/zkapps/o1js/keccak.mdx index ea0561815..f42790ace 100644 --- a/docs/zkapps/o1js/keccak.mdx +++ b/docs/zkapps/o1js/keccak.mdx @@ -12,12 +12,6 @@ keywords: - data structures --- -:::info - -zkApp programmability is not yet available on the Mina **Mainnet**, but zkApps can now be deployed on the Mina **Devnet**. - -::: - # Keccak (SHA-3) Keccak is a flexible cryptographic hash function that provides more security than traditional SHA hash algorithms. diff --git a/docs/zkapps/o1js/merkle-tree.mdx b/docs/zkapps/o1js/merkle-tree.mdx index 7077191a7..d8f483c7e 100644 --- a/docs/zkapps/o1js/merkle-tree.mdx +++ b/docs/zkapps/o1js/merkle-tree.mdx @@ -11,15 +11,9 @@ keywords: - data structures --- -:::info - -zkApp programmability is not yet available on the Mina **Mainnet**, but zkApps can now be deployed on the Mina **Devnet**. - -::: - # Merkle Tree -zkApp accounts can store only a limited amount of data on chain so that Mina's chain remains succinct and does not become bloated. +zkApp accounts can store only a limited amount of data on chain so that Mina's chain remains succinct and does not become bloated. But some zkApps might require you to access more than what you can store on-chain in a zkApp account. ## Referencing off-chain data @@ -30,7 +24,7 @@ But how can you achieve that? The answer is a Merkle tree! Merkle trees (or simi Merkle trees are special binary trees in which every leaf (the nodes at the very bottom of the tree!) are cryptographic hashes of the underlying pieces of data, and the internal nodes are labeled with the cryptographic hash of the concatenated labels (hashes) of its child nodes. -By following this algorithm to the very top, you end up with one single node (the root node) that stores the root hash of the tree. The root hash is a reference to all pieces of data that were included in the tree's leaves, so you can reference large amounts of data by using one small hash. +By following this algorithm to the very top, you end up with one single node (the root node) that stores the root hash of the tree. The root hash is a reference to all pieces of data that were included in the tree's leaves, so you can reference large amounts of data by using one small hash. Another benefit of Merkle trees is the witness, also known as a Merkle proof or Merkle path. The witness is the path from one specific leaf node to the very top of the tree (the root). Merkle witnesses are proofs of inclusion that prove that one specific piece of data (for example, an account in the ledger or the scores on a leaderboard) exists within the entire tree. diff --git a/docs/zkapps/o1js/recursion.mdx b/docs/zkapps/o1js/recursion.mdx index 80f27c555..fda80b2c0 100644 --- a/docs/zkapps/o1js/recursion.mdx +++ b/docs/zkapps/o1js/recursion.mdx @@ -14,12 +14,6 @@ keywords: - blockchain compression --- -:::info - -zkApp programmability is not yet available on the Mina **Mainnet**, but zkApps can now be deployed on the Mina **Devnet**. - -::: - # Recursion Kimchi, the custom proof system that backs o1js, supports arbitrary infinite recursive proof construction of circuits through integration with the Pickles recursive system. Mina Protocol is the only blockchain that offers infinite recursion. diff --git a/docs/zkapps/o1js/sha256.mdx b/docs/zkapps/o1js/sha256.mdx index b10425798..d07557559 100644 --- a/docs/zkapps/o1js/sha256.mdx +++ b/docs/zkapps/o1js/sha256.mdx @@ -13,12 +13,6 @@ keywords: - data structures --- -:::info - -zkApp programmability is not yet available on the Mina **Mainnet**, but zkApps can now be deployed on the Mina **Devnet**. - -::: - # SHA-256 SHA-2 is a set of cryptographic hash functions designed by the National Security Agency (NSA) as an improved version of SHA-1, offering enhanced security and comprising multiple variants based on hash size, such as SHA-256 and SHA-512. @@ -27,7 +21,7 @@ It is also the predecessor of [Keccak (SHA-3)](/zkapps/o1js/keccak). The SHA-2 f ## What is SHA-2 and SHA-256? SHA-256, a part of the SHA-2 family, is a cryptographic hash function that generates a 256-bit (32-byte) hash output, -widely used for traditional Web2 applications and protocols and blockchain technology. For example, Bitcoin's block headers are hashed twice using SHA-256. +widely used for traditional Web2 applications and protocols and blockchain technology. For example, Bitcoin's block headers are hashed twice using SHA-256. ## SHA-256 and Poseidon diff --git a/docs/zkapps/roadmap.mdx b/docs/zkapps/roadmap.mdx index 7dba78c5a..0423cf8c1 100644 --- a/docs/zkapps/roadmap.mdx +++ b/docs/zkapps/roadmap.mdx @@ -2,7 +2,7 @@ title: zkApps and o1js Roadmap hide_title: true sidebar_label: Roadmap -description: zkApps and o1js roadmap, features, enhancements, and future development plans. +description: zkApps and o1js roadmap, features, enhancements, and future development plans. keywords: - zkapps - roadmap @@ -16,12 +16,6 @@ keywords: import Subhead from '@site/src/components/common/Subhead'; -:::info - -zkApp programmability is not yet available on the Mina **Mainnet**, but zkApps can now be deployed on the Mina **Devnet**. - -::: - # zkApps and o1js Roadmap High-level overview of features available now, next, and later @@ -32,4 +26,3 @@ zkApp programmability is not yet available on the Mina **Mainnet**, but zkApps c /> To stay up to date with zkApps and o1js, follow the [What's New in o1js](https://blog.o1labs.org/search?q=o1js) monthly updates. - diff --git a/docs/zkapps/tutorials/01-hello-world.mdx b/docs/zkapps/tutorials/01-hello-world.mdx index 0ae85a9a7..d1821d478 100644 --- a/docs/zkapps/tutorials/01-hello-world.mdx +++ b/docs/zkapps/tutorials/01-hello-world.mdx @@ -18,12 +18,6 @@ keywords: import ResponsiveVideo from '@site/src/components/common/ResponsiveVideo'; -:::info - -zkApp programmability is not yet available on the Mina **Mainnet**, but zkApps can now be deployed on the Mina **Devnet**. - -::: - # Tutorial 1: Hello World This Hello World tutorial helps you get started with o1js, zkApps, and programming with zero knowledge proofs. diff --git a/docs/zkapps/tutorials/02-private-inputs-hash-functions.mdx b/docs/zkapps/tutorials/02-private-inputs-hash-functions.mdx index 5e9b3a03c..489acd173 100644 --- a/docs/zkapps/tutorials/02-private-inputs-hash-functions.mdx +++ b/docs/zkapps/tutorials/02-private-inputs-hash-functions.mdx @@ -18,12 +18,6 @@ keywords: - typescript --- -:::info - -zkApp programmability is not yet available on the Mina **Mainnet**, but zkApps can now be deployed on the Mina **Devnet**. - -::: - # Tutorial 2: Private Inputs and Hash Functions In the [Hello World](hello-world) tutorial, you built a basic zkApp smart contract with o1js with a single state variable that could be updated if you knew the square of that number. @@ -81,8 +75,8 @@ Ensure your environment meets the [Prerequisites](/zkapps/tutorials#prerequisite git remote add origin git push -u origin main ``` - - The `zk project` command creates the `02-private-inputs-and-hash-functions` directory that contains the scaffolding for your project, including tools such as the Prettier code formatting tool, the ESLint static code analysis tool, and the Jest Javascript testing framework. + + The `zk project` command creates the `02-private-inputs-and-hash-functions` directory that contains the scaffolding for your project, including tools such as the Prettier code formatting tool, the ESLint static code analysis tool, and the Jest Javascript testing framework. 1. Change into the `02-private-inputs-and-hash-functions` directory and list the contents: @@ -109,7 +103,7 @@ Ensure your environment meets the [Prerequisites](/zkapps/tutorials#prerequisite tsconfig.json ``` -For this tutorial, you run commands from the root of the `02-private-inputs-and-hash-functions` directory as you work in the `src` directory on files that contain the TypeScript code for the smart contract. +For this tutorial, you run commands from the root of the `02-private-inputs-and-hash-functions` directory as you work in the `src` directory on files that contain the TypeScript code for the smart contract. Each time you make updates, then build or deploy, the TypeScript code is compiled into JavaScript in the `build` directory. @@ -133,7 +127,7 @@ Start by deleting the default files that come with the new project. ``` - The `zk file` command created the `src/IncrementSecret.ts` file and the `src/IncrementSecret.test.ts` test file. - - However, this tutorial does not include writing tests, so you just use the `main.ts` file as a script to interact with the smart contract and observe how it works. + - However, this tutorial does not include writing tests, so you just use the `main.ts` file as a script to interact with the smart contract and observe how it works. 1. Now, open `src/index.ts` in a text editor and change it to look like: @@ -147,7 +141,7 @@ Start by deleting the default files that come with the new project. ### Copy the example files -This tutorial relies on the completed code in the [02-private-inputs-and-hash-functions/src/](https://github.com/o1-labs/docs2/blob/main/examples/zkapps/02-private-inputs-and-hash-functions/src/) example files. +This tutorial relies on the completed code in the [02-private-inputs-and-hash-functions/src/](https://github.com/o1-labs/docs2/blob/main/examples/zkapps/02-private-inputs-and-hash-functions/src/) example files. 1. First, open the [IncrementSecret.ts](https://github.com/o1-labs/docs2/blob/main/examples/zkapps/02-private-inputs-and-hash-functions/src/IncrementSecret.ts) example file. @@ -157,7 +151,7 @@ This tutorial relies on the completed code in the [02-private-inputs-and-hash-fu 1. Copy the entire contents of the file into your smart contract in the `main.ts` file. -Now you are ready to review the imports in the smart contract. +Now you are ready to review the imports in the smart contract. ## Write the smart contract @@ -165,11 +159,11 @@ Now we'll build the smart contract for our application. ### Imports -The `import` statement in the `IncrementSecret.ts` file brings in other packages and dependencies to use in your smart contract. +The `import` statement in the `IncrementSecret.ts` file brings in other packages and dependencies to use in your smart contract. :::info -All functions used inside a smart contract must operate on o1js compatible data types: `Field` types and other types built on top of `Field` types. +All functions used inside a smart contract must operate on o1js compatible data types: `Field` types and other types built on top of `Field` types. :::info @@ -229,11 +223,11 @@ This smart contract uses a secret number and the second Field, `salt`. The `incrementSecret()` method checks that the hash of the salt and the secret is equal to the current state `x`: -- If this is the case, add `1` to the secret and set `x` to the hash of the salt and this new secret. +- If this is the case, add `1` to the secret and set `x` to the hash of the salt and this new secret. - o1js creates a proof of this fact and a JSON description of the state updates to be made on the zkApp account, such as to store the new hash value. - Together, this forms a transaction that can be sent to the Mina network to update the zkApp account. -Because zkApp smart contracts are run off chain, your salt and secret remain private and are never transmitted anywhere. +Because zkApp smart contracts are run off chain, your salt and secret remain private and are never transmitted anywhere. Only the result, updating `x` on-chain state to `hash([ salt, secret + 1])` is revealed. Because the salt and secret can't be deduced from their hash, they remain private. @@ -241,7 +235,7 @@ Only the result, updating `x` on-chain state to `hash([ salt, secret + 1])` is r Cryptographic salt adds an additional layer of security to a smart contract. The extra `salt` argument prevents a possible attack on the smart contract. If you just use `secret`, the contract is vulnerable to discovery by an attacker. An attacker could try hashing likely secrets and then check if the hash matches the hash stored in the smart contract. If the hash were to match, then the attacker knows they have discovered the secret. This scenario is particularly concerning if the secret is likely to be within a particular subset of possible values, say between 1 and 10,000. In that case, with just 10,000 hashes, the attacker could discover the secret. -Adding salt as a second input to the contract code makes it harder for an attacker to reverse engineer the code and gain access to the contract. Salt makes the contract more secure and helps protect the data stored within it. For optimal security, the salt is known only to you and is typically random. +Adding salt as a second input to the contract code makes it harder for an attacker to reverse engineer the code and gain access to the contract. Salt makes the contract more secure and helps protect the data stored within it. For optimal security, the salt is known only to you and is typically random. ## Main @@ -301,4 +295,4 @@ The `state` strings are different because `Field.random()` generates the salt. Congratulations! You built a smart contract that uses privacy and hash functions. -To deploy zkApps to a live network, see [Tutorial 3: Deploy to a Live Network](deploying-to-a-network). +To deploy zkApps to a live network, see [Tutorial 3: Deploy to a Live Network](deploying-to-a-network). diff --git a/docs/zkapps/tutorials/03-deploying-to-a-network.mdx b/docs/zkapps/tutorials/03-deploying-to-a-network.mdx index c352ba1d9..163415eb8 100644 --- a/docs/zkapps/tutorials/03-deploying-to-a-network.mdx +++ b/docs/zkapps/tutorials/03-deploying-to-a-network.mdx @@ -18,19 +18,13 @@ keywords: import ResponsiveVideo from '@site/src/components/common/ResponsiveVideo'; -:::info - -zkApp programmability is not yet available on the Mina **Mainnet**, but zkApps can now be deployed on the Mina **Devnet**. - -::: - # Tutorial 3: Deploy to a Live Network -In previous tutorials, you learned how to deploy and execute transactions on a local network. +In previous tutorials, you learned how to deploy and execute transactions on a local network. In this tutorial, you will use the `zk config` command to create the deploy alias, request tMINA funds to pay for transaction fees, and deploy zkApp to a live network. -This tutorial reuses the `Square` contract that you created in [Tutorial 1: Hello World](hello-world). +This tutorial reuses the `Square` contract that you created in [Tutorial 1: Hello World](hello-world). ## Prerequisites @@ -87,11 +81,11 @@ npm update -g zkapp-cli git push -u origin main ``` - The `zk project` command creates the `03-deploying-to-a-live-network` directory that contains the scaffolding for your project, including tools such as the Prettier code formatting, the ESLint static code analysis, and the Jest JavaScript testing framework. + The `zk project` command creates the `03-deploying-to-a-live-network` directory that contains the scaffolding for your project, including tools such as the Prettier code formatting, the ESLint static code analysis, and the Jest JavaScript testing framework. 1. Change into the `03-deploying-to-a-live-network` directory. -For this tutorial, you run commands from the root of the `03-deploying-to-a-live-network` directory as you work in the `src` directory on files that contain the TypeScript code for the smart contract. +For this tutorial, you run commands from the root of the `03-deploying-to-a-live-network` directory as you work in the `src` directory on files that contain the TypeScript code for the smart contract. Each time you make updates, then build or deploy, the TypeScript code is compiled into JavaScript in the `build` directory. @@ -117,17 +111,17 @@ You installed the zkApp CLI as part of the [Prerequisites](/zkapps/tutorials#pre In some cases, you might need to create a custom account for your zkApp, programmatically parameterize a zkApp before you initialize it, or create a smart contract programmatically for users as part of an application. For details, please see [Interacting with zkApps server-side](/zkapps/tutorials/interacting-with-zkapps-server-side). -## Deploy the smart contract +## Deploy the smart contract -The `config.json` configuration file contains the configuration to deploy your zkApp. This file was automatically created during the project scaffold with the `zk project` command. +The `config.json` configuration file contains the configuration to deploy your zkApp. This file was automatically created during the project scaffold with the `zk project` command. -However, the generated configuration file does not yet contain the deploy alias. +However, the generated configuration file does not yet contain the deploy alias. ### Deploy alias -The `zk config` command prompts guide you to create a deploy alias in your project `config.json` file. +The `zk config` command prompts guide you to create a deploy alias in your project `config.json` file. -You can have one or more deploy aliases for your project. +You can have one or more deploy aliases for your project. A deploy alias consists of: @@ -148,15 +142,15 @@ A deploy alias consists of: ``` For this tutorial on Devnet, use: - - - Deploy alias name: `devnet` - + + - Deploy alias name: `devnet` + This tutorial uses `devnet`, but the deploy alias name can be anything and does not have to match the network name. - + - Target network kind: `Testnet` - + - Mina GraphQL API URL: `https://api.minascan.io/node/devnet/v1/graphql` - + - Transaction fee to use when deploying (in MINA): `0.1` 1. When prompted to choose an account to pay transaction fees, select: @@ -174,7 +168,7 @@ A deploy alias consists of: A third option to choose another saved fee payer account is shown only if you have multiple cached fee payer accounts. -1. Select to create a new fee payer key pair: +1. Select to create a new fee payer key pair: ```sh Create a new fee payer key pair @@ -206,7 +200,7 @@ A deploy alias consists of: 1. Request funds from the Testnet Faucet to fund your fee payer account. - Follow the prompts to request tMINA. + Follow the prompts to request tMINA. To get funds on the Devnet, use the URL that was shown in the zkApp CLI output: - Visit `https://faucet.minaprotocol.com/?address=` - Choose the corresponding network you're going to deploy your zkApp to (`Devnet` in this case) @@ -227,8 +221,8 @@ A deploy alias consists of: > devnet ``` - A verification key for your smart contract is generated (takes 10-30 seconds). - + A verification key for your smart contract is generated (takes 10-30 seconds). + The deploy process is output: ```text @@ -242,8 +236,8 @@ A deploy alias consists of: ✔ Build transaction ``` -1. Review and confirm the details of the transaction: - +1. Review and confirm the details of the transaction: + ```text ✔ Confirm to send transaction @@ -264,7 +258,7 @@ A deploy alias consists of: |-----------------|-------------------------------------------------| ``` - + When prompted, type `yes` to confirm and send the transaction to the network. ```text @@ -279,7 +273,7 @@ A deploy alias consists of: https://minascan.io/devnet/tx/?type=zk-tx ``` -1. To see the zkApp transaction and navigate to accounts involved you can follow the transaction link provided to you in zkApp CLI output. +1. To see the zkApp transaction and navigate to accounts involved you can follow the transaction link provided to you in zkApp CLI output. Or use the [Minascan](https://minascan.io) explorer to search for the account with deployed zkApp. ## Success @@ -307,13 +301,13 @@ To test, configure, and deploy your zkApp on a local representation of the Mina ## About the Smart Contract Transactions -Because this tutorial used the smart contract from `Tutorial 1: Hello World`, the smart contract's `editState` permissions require that the transaction must contain a valid zk proof that was created by the private key associated with this zkApp account. +Because this tutorial used the smart contract from `Tutorial 1: Hello World`, the smart contract's `editState` permissions require that the transaction must contain a valid zk proof that was created by the private key associated with this zkApp account. -- When a user interacts with this smart contract by providing a proof, the proof is generated locally on the user's device and included in a transaction. -- When the transaction is submitted to the network, the proof is checked to ensure it is correct and matches the on-chain verification key. +- When a user interacts with this smart contract by providing a proof, the proof is generated locally on the user's device and included in a transaction. +- When the transaction is submitted to the network, the proof is checked to ensure it is correct and matches the on-chain verification key. - After the transaction is accepted, the proof and transaction are recursively proved and bundled into Mina's recursive zero knowledge proof. -When you change the smart contract code, the associated verification key also changes. Use the same steps to redeploy your zkApp. +When you change the smart contract code, the associated verification key also changes. Use the same steps to redeploy your zkApp. For a typical smart contract, permissions are set to only allow proof authorization. You learn more about setting permissions in the later tutorials. diff --git a/docs/zkapps/tutorials/04-zkapp-ui-with-react.mdx b/docs/zkapps/tutorials/04-zkapp-ui-with-react.mdx index bc07d2be7..5b1b2c311 100644 --- a/docs/zkapps/tutorials/04-zkapp-ui-with-react.mdx +++ b/docs/zkapps/tutorials/04-zkapp-ui-with-react.mdx @@ -16,20 +16,14 @@ keywords: - mina --- -:::info - -zkApp programmability is not yet available on the Mina **Mainnet**, but zkApps can now be deployed on the Mina **Devnet**. - -::: - # Tutorial 4: Build a zkApp UI in the Browser with React You're making excellent progress in your zkApp journey: -- In the [Hello World](hello-world) tutorial, you built a basic zkApp smart contract with o1js. +- In the [Hello World](hello-world) tutorial, you built a basic zkApp smart contract with o1js. - In [Tutorial 3: Deploy to a Live Network](deploying-to-a-network), you used the `zk` commands to deploy your zkApp. -In this tutorial, you are going to implement a browser UI using `Next.js` that interacts with a smart contract. +In this tutorial, you are going to implement a browser UI using `Next.js` that interacts with a smart contract. ## Prerequisites @@ -84,21 +78,21 @@ You can have the `zk project` command scaffold the UI for your project. nuxt empty none - ``` + ``` -1. If you are prompted to install the required Next packages, press **y** to proceed. +1. If you are prompted to install the required Next packages, press **y** to proceed. 1. Select **yes** at the `? Do you want to set up your project for deployment to Github Pages? …` prompt. -1. If you are prompted to install the required Next packages, press **y** to proceed. +1. If you are prompted to install the required Next packages, press **y** to proceed. 1. Select **Yes** at the `? Would you like to use TypeScript with this project?` prompt. 1. Select **No** at the `? Would you like to use ESLint with this project?` prompt. 1. Select **No** at the `? Would you like to use Tailwind CSS with this project?` prompt. Your UI is created in the project directory: `04-zkapp-browser-ui/ui` with two directories: - - `contracts`: The smart contract code + - `contracts`: The smart contract code - `ui`: Where you write the UI code -For this tutorial, you run commands from the root of the `04-zkapp-browser-ui/ui` directory. You work in the `ui/src/pages` directory on TypeScript files that contain the UI code. +For this tutorial, you run commands from the root of the `04-zkapp-browser-ui/ui` directory. You work in the `ui/src/pages` directory on TypeScript files that contain the UI code. Each time you make updates, then build or deploy, the TypeScript code is compiled into JavaScript in the `build` directory. @@ -169,7 +163,7 @@ Because o1js code is computationally intensive, it's helpful to use web workers. The example project has a completed app. The `index.page.tsx` file is the entry file for your application and contains the main logic for the browser UI that is ready to deploy to GitHub Pages. -1. Download the [index.page.tsx](https://github.com/o1-labs/docs2/blob/main/examples/zkapps/04-zkapp-browser-ui/ui/src/pages/index.page.tsx) example file. +1. Download the [index.page.tsx](https://github.com/o1-labs/docs2/blob/main/examples/zkapps/04-zkapp-browser-ui/ui/src/pages/index.page.tsx) example file. 1. Move the `index.page.tsx` file to your local `04-zkapp-browser-ui/ui/src/pages` directory. @@ -196,7 +190,7 @@ The example project has a completed app. The `index.page.tsx` file is the entry }, ``` - Depending on the network you are going to work with you might want to consider changing the GraphQL endpoint in the `setActiveInstanceToDevnet` function. + Depending on the network you are going to work with you might want to consider changing the GraphQL endpoint in the `setActiveInstanceToDevnet` function. Mind the supported networks by `Auro Wallet` though. ### Add state @@ -224,8 +218,8 @@ To learn more about `useState` hooks, see [built-in React hooks](https://react.d This `04-zkapp-browser-ui/ui/src/pages/index.page.tsx` code adds a functions to set up zkApp: -- The Boolean `hasBeenSetup` ensures that the react feature `useEffect` is run only once. -To learn more about `useEffect` hooks, see [useEffect](https://react.dev/reference/react/useEffect) in the React API reference documentation. +- The Boolean `hasBeenSetup` ensures that the react feature `useEffect` is run only once. +To learn more about `useEffect` hooks, see [useEffect](https://react.dev/reference/react/useEffect) in the React API reference documentation. - This code also sets up your web worker client that interacts with the web worker running o1js code to ensure the computationally heavy o1js code doesn't block the UI thread. @@ -313,7 +307,7 @@ To learn more about `useEffect` hooks, see [useEffect](https://react.dev/referen ### Run the React app -Execute the following commands being within the `04-zkapp-browser-ui/ui/` directory. +Execute the following commands being within the `04-zkapp-browser-ui/ui/` directory. 1. To start the development server and serve your UI application at the URL `localhost:3000`: @@ -329,7 +323,7 @@ Execute the following commands being within the `04-zkapp-browser-ui/ui/` direct The zkApp UI in the web browser shows the current state of the zkApp and has buttons to send a transaction and get the latest zkApps on-chain state. - Your browser refreshes automatically when you update the source code. + Your browser refreshes automatically when you update the source code. 1. If prompted, request the funds from the Testnet Faucet service to fund your fee payer account. 1. And in the second terminal window: @@ -342,7 +336,7 @@ Execute the following commands being within the `04-zkapp-browser-ui/ui/` direct ### Wait for the fee payer account to be funded -Now that the UI setup is finished, a new effect waits for the fee payer account to be funded if it didn't before by checking the account presence in ledger. +Now that the UI setup is finished, a new effect waits for the fee payer account to be funded if it didn't before by checking the account presence in ledger. Don't forget that if the account has been newly created, it must be funded from the Faucet. @@ -515,7 +509,7 @@ The UI has three sections: - `setup` lets the user know when the zkApp has finished loading. - `accountDoesNotExist` gives the user a link to the Faucet if their account hasn't been funded. -- `mainContent` shows the current zkApp on-chain state and buttons to let users interact with zkApp. +- `mainContent` shows the current zkApp on-chain state and buttons to let users interact with zkApp. The buttons allow the user to create transaction in order to update on-chain zkApp state and refresh the current on-chain zkApp state. That's it for the code review! @@ -524,14 +518,14 @@ If you've been using `npm run dev`, you can now interact with the UI application ## Deploying the application to GitHub Pages -Before you can deploy your project to GitHub Pages, you must push it to a new GitHub repository that you've created at the beginning of this tutorial. +Before you can deploy your project to GitHub Pages, you must push it to a new GitHub repository that you've created at the beginning of this tutorial. -- The GitHub repo must have the same name as the project name. +- The GitHub repo must have the same name as the project name. - In this tutorial, the project name is `04-zkapp-browser-ui`. -- The `zk project` command created the correct project name strings in the `next.config.js` and `src/pages/reactCOIServiceWorker.ts` files. +- The `zk project` command created the correct project name strings in the `next.config.js` and `src/pages/reactCOIServiceWorker.ts` files. To deploy the UI: - + 1. Change to the `04-zkapp-browser-ui/ui/` directory. 1. Run the `deploy` script by executing the following command: @@ -539,7 +533,7 @@ To deploy the UI: npm run deploy ``` -Scripts defined in the `04-zkapp-browser-ui/ui/package.json` file do the work to build your application and publish it to the GitHub Pages. +Scripts defined in the `04-zkapp-browser-ui/ui/package.json` file do the work to build your application and publish it to the GitHub Pages. After the command completion your zkApp UI will be available at: diff --git a/docs/zkapps/tutorials/05-common-types-and-functions.mdx b/docs/zkapps/tutorials/05-common-types-and-functions.mdx index b0a085bbf..37e7920fd 100644 --- a/docs/zkapps/tutorials/05-common-types-and-functions.mdx +++ b/docs/zkapps/tutorials/05-common-types-and-functions.mdx @@ -22,12 +22,6 @@ keywords: import ResponsiveVideo from '@site/src/components/common/ResponsiveVideo'; -:::info - -zkApp programmability is not yet available on the Mina **Mainnet**, but zkApps can now be deployed on the Mina **Devnet**. - -::: - # Tutorial 5: Common Types and Functions In previous tutorials, you learned how to deploy smart contracts to the network interact with them from a React UI and NodeJS. @@ -173,7 +167,7 @@ Define a Struct as one or more data types that o1js understands. For example, Fi The following example demonstrates how to use `Struct` to implement a `Point` structure and an array of points of length 8 structure. -In o1js, programs are compiled into fixed-sized circuits. This means that data structures it consumes must also be a fixed size. +In o1js, programs are compiled into fixed-sized circuits. This means that data structures it consumes must also be a fixed size. To meet the fixed-size requirement, this code declares the array in `Points8` structure to be a static size of 8. @@ -315,7 +309,7 @@ The height variable determines how many leaves are available to the application. Merkle trees in smart contracts are stored as the hash of the Merkle tree's root. Smart contract methods that update the Merkle root can take a _witness_ of the change as an argument. The [MerkleMapWitness](/zkapps/o1js-reference/classes/MerkleMapWitness) represents the Merkle path to the data for which inclusion is being proved. -A contract stores the root of a Merkle tree, where each leaf stores a number, and the smart contract has an `update` function that adds a number to the leaf. +A contract stores the root of a Merkle tree, where each leaf stores a number, and the smart contract has an `update` function that adds a number to the leaf. For example, to put a condition on a leaf update, the `update` function checks that the number added was less than 10: diff --git a/docs/zkapps/tutorials/06-offchain-storage.mdx b/docs/zkapps/tutorials/06-offchain-storage.mdx index 962800637..cb12c449d 100644 --- a/docs/zkapps/tutorials/06-offchain-storage.mdx +++ b/docs/zkapps/tutorials/06-offchain-storage.mdx @@ -16,27 +16,21 @@ keywords: - mina --- -:::info - -zkApp programmability is not yet available on the Mina **Mainnet**, but zkApps can now be deployed on the Mina **Devnet**. - -::: - # Tutorial 6: Off-Chain Storage In [Tutorial 5: Common Types and Functions](common-types-and-functions), you learned how to use Merkle trees to refer to large amounts of data stored off-chain. -This tutorial presents a library and pattern to store Merkle trees off-chain and store only the tree's root hash on-chain. +This tutorial presents a library and pattern to store Merkle trees off-chain and store only the tree's root hash on-chain. This approach is a step towards unlocking a larger set of applications that require off-chain storage. Future solutions can provide other decentralized options for zkApps that require more trustless solutions. :::experimental -This proposed solution to off-chain storage is experimental and is used only for education purposes. +This proposed solution to off-chain storage is experimental and is used only for education purposes. ::: -This tutorial provides a single-server solution to data storage for prototyping zkApps and building zkApps where some trust guarantees are reasonable. The solution proposed in this learning tutorial is appropriate for development, but is not recommended for zkApps that require trustlessness. +This tutorial provides a single-server solution to data storage for prototyping zkApps and building zkApps where some trust guarantees are reasonable. The solution proposed in this learning tutorial is appropriate for development, but is not recommended for zkApps that require trustlessness. -The single-server solution for prototyping is intended as one of several options for data availability on Mina. Mina doesn't offer an out-of-the-box solution for off-chain storage. +The single-server solution for prototyping is intended as one of several options for data availability on Mina. Mina doesn't offer an out-of-the-box solution for off-chain storage. ## Why Off-Chain Storage? @@ -68,7 +62,7 @@ This implementation requires a trust assumption for zkApps that use it: both dev This trust assumption makes it useful for prototyping applications that need off-chain storage and for putting applications into production where these trust assumptions are reasonable. This implementation is not appropriate for zkApps where a trustless solution is needed. -To learn more about this implementation and see how it works, see the [experimental-zkapp-offchain-storage](https://github.com/o1-labs/docs2/tree/main/examples/zkapps/06-offchain-storage/experimental-zkapp-offchain-storage) library. +To learn more about this implementation and see how it works, see the [experimental-zkapp-offchain-storage](https://github.com/o1-labs/docs2/tree/main/examples/zkapps/06-offchain-storage/experimental-zkapp-offchain-storage) library. ### Grant Opportunity to Develop Single-Server Off-Chain Storage @@ -87,13 +81,13 @@ Suggested improvements: The sample code for this project is provided at [examples/zkapps/06-offchain-storage/contracts](https://github.com/o1-labs/docs2/tree/main/examples/zkapps/06-offchain-storage/offchain-storage-zkapp/contracts) with a focus on: - [src/main.ts](https://github.com/o1-labs/docs2/blob/main/examples/zkapps/06-offchain-storage/offchain-storage-zkapp/contracts/src/main.ts) -- [src/NumberTreeContract.ts](https://github.com/o1-labs/docs2/blob/main/examples/zkapps/06-offchain-storage/offchain-storage-zkapp/contracts/src/NumberTreeContract.ts) +- [src/NumberTreeContract.ts](https://github.com/o1-labs/docs2/blob/main/examples/zkapps/06-offchain-storage/offchain-storage-zkapp/contracts/src/NumberTreeContract.ts) This project implements a Merkle tree where: -- Each leaf is either empty or stores a number (an o1js field), which is the data. -- Updates to the tree can update a leaf if the new number in the leaf is greater than the old number. -- The root of the tree is stored on-chain. +- Each leaf is either empty or stores a number (an o1js field), which is the data. +- Updates to the tree can update a leaf if the new number in the leaf is greater than the old number. +- The root of the tree is stored on-chain. - The tree itself is stored on an off-chain storage server. ## Prerequisites @@ -133,13 +127,13 @@ This tutorial has been tested with: ## Project structure -The `zk project` command creates the `06-off-chain-storage` directory that contains the scaffolding for your project. +The `zk project` command creates the `06-off-chain-storage` directory that contains the scaffolding for your project. -The files in the `src` directory files contain the TypeScript code for the smart contract. +The files in the `src` directory files contain the TypeScript code for the smart contract. Each time you make updates, then build or deploy, the TypeScript code is compiled into JavaScript in the `build` directory. -For all projects, you run `zk` commands from the root of your project directory. +For all projects, you run `zk` commands from the root of your project directory. ## Prepare the project @@ -190,7 +184,7 @@ $ node node_modules/experimental-zkapp-offchain-storage/build/src/storageServer. A full copy of the [NumberTreeContract.ts](https://github.com/o1-labs/docs2/blob/main/examples/zkapps/06-offchain-storage/offchain-storage-zkapp/contracts/src/NumberTreeContract.ts) example file is provided. -1. Open `NumberTreeContract.ts` in your editor. +1. Open `NumberTreeContract.ts` in your editor. 1. Start by adding the imports: @@ -226,7 +220,7 @@ The `OffChainStorage` object contains the functions for interacting with off-cha - `assertRootUpdateValid`: A function used in smart contracts to prove updates to the smart contract's currently stored tree root result in a tree root that is being stored by the storage server. - `mapToTree`: A storage function to convert maps to trees. Internally the storage server is using maps from tree indices to leafs. -The `MerkleWitness8` is a type of Merkle tree witness required for o1js to use the same instances of the witness cross-library. Other types of Merkle trees are available for input, such as `MerkleWitness32` and `MerkleWitness256`. +The `MerkleWitness8` is a type of Merkle tree witness required for o1js to use the same instances of the witness cross-library. Other types of Merkle trees are available for input, such as `MerkleWitness32` and `MerkleWitness256`. 3. Now, set up your smart contract: @@ -255,7 +249,7 @@ export class NumberTreeContract extends SmartContract { ... ``` -This code adds three pieces of state to the contract: +This code adds three pieces of state to the contract: - The public key of the storage server - The storageNumber used to ensure the storage server is actively storing states @@ -331,7 +325,7 @@ That completes the smart contract! ## Implementing `main.ts` -Since much of the logic in the `main.ts` file is repeated from earlier tutorials, this tutorial reviews just the relevant parts. +Since much of the logic in the `main.ts` file is repeated from earlier tutorials, this tutorial reviews just the relevant parts. 1. Download the [main.ts](https://github.com/o1-labs/docs2/blob/main/examples/zkapps/06-offchain-storage/offchain-storage-zkapp/contracts/src/main.ts) example file. @@ -339,9 +333,9 @@ Since much of the logic in the `main.ts` file is repeated from earlier tutorials 1. Open it in your editor. -The `main.ts` file contains logic for running the contract locally and for deploying and interacting with it on Devnet. +The `main.ts` file contains logic for running the contract locally and for deploying and interacting with it on Devnet. -This is a useful pattern when developing a new contract. +This is a useful pattern when developing a new contract. ### Connect to the off-chain storage server diff --git a/docs/zkapps/tutorials/07-oracle.mdx b/docs/zkapps/tutorials/07-oracle.mdx index 117b62067..cf2645fbd 100644 --- a/docs/zkapps/tutorials/07-oracle.mdx +++ b/docs/zkapps/tutorials/07-oracle.mdx @@ -16,12 +16,6 @@ keywords: import ResponsiveVideo from '@site/src/components/common/ResponsiveVideo'; -:::info - -zkApp programmability is not yet available on the Mina **Mainnet**, but zkApps can now be deployed on the Mina **Devnet**. - -::: - # Tutorial 7: Oracles You can use an oracle when your smart contract needs to consume data from the outside world. @@ -103,7 +97,7 @@ The demo oracle for user with id `1` is available at https://07-oracles.vercel.a } ``` -The user with an `id` of `2` has a credit score that is below the threshold specified in the smart contract. +The user with an `id` of `2` has a credit score that is below the threshold specified in the smart contract. The demo oracle for user with id `2` with a lower credit score is available at https://07-oracles.vercel.app/api/credit-score?user=2 and shows this response: ```json @@ -124,7 +118,7 @@ You can generate the Mina-compatible public/private key pair for your oracle by npm run keygen ``` -This command runs the code in the [keygen.js](https://github.com/o1-labs/docs2/blob/main/examples/zkapps/07-oracles/oracle/scripts/keygen.js) file. +This command runs the code in the [keygen.js](https://github.com/o1-labs/docs2/blob/main/examples/zkapps/07-oracles/oracle/scripts/keygen.js) file. This file is the part of the oracle `Next.js` application, source code of which is available [here](https://github.com/o1-labs/docs2/tree/main/examples/zkapps/07-oracles/oracle). ## Smart Contract @@ -323,7 +317,7 @@ With this foundation, you can emit a verified event. - The first argument to `emitEvent()` is an arbitrary string name, because a smart contract could emit more than one type of event. - The second argument can be any value, as long as it matches the type defined for the event. -In this case, the event has the `Field` type, but it could be a more complicated type built on `Fields`, if the situation called for it. +In this case, the event has the `Field` type, but it could be a more complicated type built on `Fields`, if the situation called for it. Emitted events can be fetched using the [Archive-Node-API](/zkapps/writing-a-zkapp/feature-overview/fetch-events-and-actions). ```ts @@ -505,5 +499,5 @@ To run the tests: Note that writing a test that calls an API is generally not a best practice, but it's convenient for the sake of this tutorial. You can also mock your HTTP requests. -Congratulations! You have just built a simple oracle using o1js and the Mina blockchain. +Congratulations! You have just built a simple oracle using o1js and the Mina blockchain. You can find the complete code for this example [here](https://github.com/o1-labs/docs2/tree/main/examples/zkapps/07-oracles). diff --git a/docs/zkapps/tutorials/08-custom-tokens.mdx b/docs/zkapps/tutorials/08-custom-tokens.mdx index 59a6e51f3..eec9234dc 100644 --- a/docs/zkapps/tutorials/08-custom-tokens.mdx +++ b/docs/zkapps/tutorials/08-custom-tokens.mdx @@ -15,12 +15,6 @@ keywords: - tokens --- -:::info - -zkApp programmability is not yet available on the Mina **Mainnet**, but zkApps can now be deployed on the Mina **Devnet**. - -::: - # Tutorial 8: Custom Tokens In this tutorial, you learn to create custom tokens. @@ -31,7 +25,7 @@ To create a new token, one creates a smart contract, which becomes the manager f The manager account may also set a token symbol for its token, such as in this example, `MYTKN`. Uniqueness is not enforced for token names. Instead the public key of the manager account is used to identify tokens. -In this tutorial, you review smart contract code that creates and manages new tokens. +In this tutorial, you review smart contract code that creates and manages new tokens. The full example code is provided in the [08-custom-tokens/src/](https://github.com/o1-labs/docs2/tree/main/examples/zkapps/08-custom-tokens/src) example files. @@ -141,7 +135,7 @@ A full copy of the [BasicTokenContract.ts](https://github.com/o1-labs/docs2/blob ### Imports and smart contract structure -First, bring in imports and set up the structure for the smart contract. +First, bring in imports and set up the structure for the smart contract. The single state variable `totalAmountInCirculation` tracks how many tokens exist. @@ -180,11 +174,11 @@ export class BasicTokenContract extends SmartContract { ### init() and mint() methods -Next, add an init method and a method that mints tokens. +Next, add an init method and a method that mints tokens. - Set the token symbol (MYTKN) in the `init()` method. - To start tracking the amount in circulation, set it to zero. -- Write a function to mint new tokens and send them to a recipient. +- Write a function to mint new tokens and send them to a recipient. This function checks that a signature has been provided by the zkApp account, so that only the zkApp account can call the `mint()` method. @@ -225,7 +219,7 @@ Next, add an init method and a method that mints tokens. ### Send function -Finally, write a send function. +Finally, write a send function. - Holders of the MYTKN token call the `sendTokens()` method to send tokens to other Mina accounts. @@ -244,7 +238,7 @@ Finally, write a send function. } ``` -That completes a review of a basic token. +That completes a review of a basic token. ## Examples diff --git a/docs/zkapps/tutorials/09-recursion.mdx b/docs/zkapps/tutorials/09-recursion.mdx index e8be53fd8..9c8e726c5 100644 --- a/docs/zkapps/tutorials/09-recursion.mdx +++ b/docs/zkapps/tutorials/09-recursion.mdx @@ -16,12 +16,6 @@ keywords: - mina --- -:::info - -zkApp programmability is not yet available on the Mina **Mainnet**, but zkApps can now be deployed on the Mina **Devnet**. - -::: - # Tutorial 9: Recursion One of the most powerful features of zkApps is [recursion](/zkapps/o1js/recursion). diff --git a/docs/zkapps/tutorials/10-account-updates.mdx b/docs/zkapps/tutorials/10-account-updates.mdx index b061c1189..edba2d1f2 100644 --- a/docs/zkapps/tutorials/10-account-updates.mdx +++ b/docs/zkapps/tutorials/10-account-updates.mdx @@ -17,12 +17,6 @@ keywords: - mina --- -:::info - -zkApp programmability is not yet available on the Mina **Mainnet**, but zkApps can now be deployed on the Mina **Devnet**. - -::: - # Tutorial 10: Account Updates The fundamental data structure that Mina transactions are built from is called an _account update_. Account updates are a flexible and powerful data structure that can express all kinds of updates, events, and preconditions you use to develop smart contracts. diff --git a/docs/zkapps/tutorials/11-advanced-account-updates.mdx b/docs/zkapps/tutorials/11-advanced-account-updates.mdx index bf2b41ef3..e9171f819 100644 --- a/docs/zkapps/tutorials/11-advanced-account-updates.mdx +++ b/docs/zkapps/tutorials/11-advanced-account-updates.mdx @@ -13,12 +13,6 @@ keywords: - balance change check--- --- -:::info - -zkApp programmability is not yet available on the Mina **Mainnet**, but zkApps can now be deployed on the Mina **Devnet**. - -::: - # Tutorial 11: Advanced Account Updates In the last tutorial, you learned the structure of account updates and how zkApp transactions are composed of account updates. diff --git a/docs/zkapps/tutorials/anonymous-message-board.mdx b/docs/zkapps/tutorials/anonymous-message-board.mdx index ce6ce0e64..54296be69 100644 --- a/docs/zkapps/tutorials/anonymous-message-board.mdx +++ b/docs/zkapps/tutorials/anonymous-message-board.mdx @@ -12,19 +12,13 @@ keywords: - mina --- -:::info - -zkApp programmability is not yet available on the Mina **Mainnet**, but zkApps can now be deployed on the Mina **Devnet**. - -::: - # Anonymous Message Board Tutorial This example shows you how to put building zkApp ideas into practice as you walk through designing and implementing of a semi-anonymous messaging protocol. -In this tutorial, you build a smart contract that allows users to publish messages semi-anonymously. -- The contract allows a specific set of users to create new messages but does not disclose which user creates the message. -- This semi-anonymous messaging leverages one aspect of a person's identity without revealing exactly who they are. +In this tutorial, you build a smart contract that allows users to publish messages semi-anonymously. +- The contract allows a specific set of users to create new messages but does not disclose which user creates the message. +- This semi-anonymous messaging leverages one aspect of a person's identity without revealing exactly who they are. An example use case for this semi-anonymous contract is to enable a DAO member to make credible statements on behalf of their DAO without revealing their specific individual identity. @@ -51,22 +45,22 @@ This tutorial has been tested with: ```sh $ zk project --ui none message-board ``` - - The `zk project` command creates a directory with a new project template that is fully set up and ready for local development. Like all zk projects, a git repository is initialized in the project directory. By convention, the `main` branch is the default branch. + + The `zk project` command creates a directory with a new project template that is fully set up and ready for local development. Like all zk projects, a git repository is initialized in the project directory. By convention, the `main` branch is the default branch. 1. Change to the project directory: - ```sh + ```sh cd message-board ``` - For this tutorial, you run commands from the root of the `message-board` directory as you work in the `src` directory on files that contain the TypeScript code for the smart contract. - + For this tutorial, you run commands from the root of the `message-board` directory as you work in the `src` directory on files that contain the TypeScript code for the smart contract. + Each time you make updates, then build or deploy, the TypeScript code is compiled into JavaScript in the `build` directory. See the included [README](https://github.com/o1-labs/docs2/blob/main/examples/zkapps/anonymous-message-board/README.md) file with usage instructions. ### Prepare the project -Example smart contract files come with the new project, you can delete them if you want. +Example smart contract files come with the new project, you can delete them if you want. 1. Optional: Delete the example files not used in this tutorial: @@ -80,7 +74,7 @@ Example smart contract files come with the new project, you can delete them if y $ zk file message ``` -1. Copy the entire contents of the [message.ts](https://github.com/o1-labs/docs2/blob/main/examples/zkapps/anonymous-message-board/src/message.ts) example file into your local `message-board/src/message.ts` file. +1. Copy the entire contents of the [message.ts](https://github.com/o1-labs/docs2/blob/main/examples/zkapps/anonymous-message-board/src/message.ts) example file into your local `message-board/src/message.ts` file. ```ts import { @@ -162,10 +156,10 @@ Example smart contract files come with the new project, you can delete them if y } ``` -This code serves as the scaffolding for the rest of the tutorial and contains a smart contract called `message` with two methods: +This code serves as the scaffolding for the rest of the tutorial and contains a smart contract called `message` with two methods: -- `init()` - Similar to the `constructor` in Solidity, it's where you define any set up that needs to happen before users begin interacting with the contract. -- `publishMessage()` - The method that users invoke when they want to create a new message. +- `init()` - Similar to the `constructor` in Solidity, it's where you define any set up that needs to happen before users begin interacting with the contract. +- `publishMessage()` - The method that users invoke when they want to create a new message. The `@method` decorator tells o1js to: @@ -174,7 +168,7 @@ This code serves as the scaffolding for the rest of the tutorial and contains a ### Define on-chain state -Every Mina smart contract includes eight on-chain state variables that each store almost 256 bits of information. In more complex smart contracts, these state variables can store commitments to off-chain storage (for example, commitments for the hash of a file, the root of a Merkle tree, and so on). +Every Mina smart contract includes eight on-chain state variables that each store almost 256 bits of information. In more complex smart contracts, these state variables can store commitments to off-chain storage (for example, commitments for the hash of a file, the root of a Merkle tree, and so on). For simplicity, this tutorial stores everything on-chain. @@ -182,7 +176,7 @@ For simplicity, this tutorial stores everything on-chain. General purpose off-chain storage libraries are appropriate only for development. See [Tutorial 6: Off-Chain Storage](/zkapps/tutorials/offchain-storage). ::: -In this smart contract, one state variable stores the last message. Another stores the hash of all the previous messages so a frontend can validate message history. Three more state variables can store user public keys. +In this smart contract, one state variable stores the last message. Another stores the hash of all the previous messages so a frontend can validate message history. Three more state variables can store user public keys. It's possible to store additional public keys by Merkelizing them, but for simplicity this tutorial uses only three keys: @@ -198,7 +192,7 @@ export class Message extends SmartContract { The `@state(Field)` decorator tells o1js that the variable is stored on-chain as a `Field` type. -For practical purposes, the `Field` type is similar to the `uint256` type in Solidity. It can store large integers and addition, subtraction, and multiplication all work as expected. The only caveats are division and what happens in the event of an overflow. To learn more about finite fields, see [Finite field arithmetic](https://en.wikipedia.org/wiki/Finite_field_arithmetic). It is not required to understand exactly how field arithmetic works for this tutorial. +For practical purposes, the `Field` type is similar to the `uint256` type in Solidity. It can store large integers and addition, subtraction, and multiplication all work as expected. The only caveats are division and what happens in the event of an overflow. To learn more about finite fields, see [Finite field arithmetic](https://en.wikipedia.org/wiki/Finite_field_arithmetic). It is not required to understand exactly how field arithmetic works for this tutorial. o1js also provides `UInt32`, `UInt64`, and `Int64` types. All o1js types are composed of the `Field` type, including `PublicKey` as shown in the previous example. @@ -227,7 +221,7 @@ For this example, pass in `message` and `signerPrivateKey` arguments to check th @method async publishMessage(message: Field, signerPrivateKey: PrivateKey) { ``` -Note that all inputs are private by default and exist only on the user's local machine when the smart contract runs. The Mina network never sees private inputs. +Note that all inputs are private by default and exist only on the user's local machine when the smart contract runs. The Mina network never sees private inputs. The smart contract sends only values that are stored as state to the Mina blockchain. This means that even though the value of the `message` argument is eventually public, the value of `signerPrivateKey` never leaves the user's machine as a result of interacting with the smart contract. @@ -249,7 +243,7 @@ const user2 = this.user2.get(); const user3 = this.user3.get(); ``` -Calling the `get()` method retrieves these values from the zkApp account on-chain state. +Calling the `get()` method retrieves these values from the zkApp account on-chain state. :::note o1js uses a single network request to retrieve all on-chain state values simultaneously. @@ -283,7 +277,7 @@ The `set()` method asks the Mina nodes to update the value of their on-chain sta ### Update `messageHistoryHash` -There's one more thing to do. If you want users to be able to keep track of what has been said, then you need to store a commitment to the message history on-chain. +There's one more thing to do. If you want users to be able to keep track of what has been said, then you need to store a commitment to the message history on-chain. There are a few ways to do this, but the simplest way is to store a hash of your new `message` and your old `messageHistoryHash` every time you call `publishMessage`: @@ -306,24 +300,23 @@ If everything is correct, you see a new `./build` directory where the compiled v ## Wrapping up -This tutorial gives you a sense of what's possible with o1js. +This tutorial gives you a sense of what's possible with o1js. -The messaging protocol you built is quite simple but also very powerful. You can use this basic pattern to create a whistleblower system, an anonymous NFT project, or even anonymous DAO voting. +The messaging protocol you built is quite simple but also very powerful. You can use this basic pattern to create a whistleblower system, an anonymous NFT project, or even anonymous DAO voting. The main point is that o1js makes it easy for you to build things that don't intuitively seem possible. -Zero knowledge proofs open the door to an entirely different way of thinking about the internet. We are so excited to see what people like you will build. +Zero knowledge proofs open the door to an entirely different way of thinking about the internet. We are so excited to see what people like you will build. -Make sure to join the [#zkapps-developers](https://discord.com/channels/484437221055922177/915745847692636181) channel on Mina Protocol Discord. +Make sure to join the [#zkapps-developers](https://discord.com/channels/484437221055922177/915745847692636181) channel on Mina Protocol Discord. -## Keep going +## Keep going The logical next steps to extend this project include: -- Allow users to pass signers into the `publishMessage()` method directly so that many different organizations can use a single contract. +- Allow users to pass signers into the `publishMessage()` method directly so that many different organizations can use a single contract. Hint: You'll have to store a commitment to the signers on-chain. - Allow users to pass an arbitrarily large number of signers into the `publishMessage()` method. - Store the message history in a Merkle tree so a user interface can quickly check a subset of the messages without evaluating the entire history. - Build a shiny front end! import { showCompletionScript } from "yargs" - diff --git a/docs/zkapps/tutorials/index.mdx b/docs/zkapps/tutorials/index.mdx index ffc4f462b..538de3fcc 100644 --- a/docs/zkapps/tutorials/index.mdx +++ b/docs/zkapps/tutorials/index.mdx @@ -17,12 +17,6 @@ keywords: import ResponsiveVideo from '@site/src/components/common/ResponsiveVideo'; -:::info - -zkApp programmability is not yet available on the Mina **Mainnet**, but zkApps can now be deployed on the Mina **Devnet**. - -::: - # zkApp Developer Tutorials zkApp developer tutorials are a hands-on walk-through of use cases that guide you to achieve a defined goal. diff --git a/docs/zkapps/tutorials/interacting-with-zkapps-server-side.mdx b/docs/zkapps/tutorials/interacting-with-zkapps-server-side.mdx index 2155b7be1..74363ea6e 100644 --- a/docs/zkapps/tutorials/interacting-with-zkapps-server-side.mdx +++ b/docs/zkapps/tutorials/interacting-with-zkapps-server-side.mdx @@ -10,12 +10,6 @@ keywords: - custom deploy --- -:::info - -zkApp programmability is not yet available on the Mina **Mainnet**, but zkApps can now be deployed on the Mina **Devnet**. - -::: - # Interacting with zkApps server-side While user-facing zkApps can be written for the browser, sometimes it is useful to interact with a zkApp server-side or on your own machine. For example, when initializing a zkApp using programmatically generated information, deploying a zkApp in custom ways, or writing scripts that create transactions depending on real-world (periodically updating an on-chain value with signed data, like a keeper for an oracle) or on-chain events. diff --git a/docs/zkapps/writing-a-zkapp/feature-overview/actions-and-reducer.mdx b/docs/zkapps/writing-a-zkapp/feature-overview/actions-and-reducer.mdx index 926244887..ed79ca287 100644 --- a/docs/zkapps/writing-a-zkapp/feature-overview/actions-and-reducer.mdx +++ b/docs/zkapps/writing-a-zkapp/feature-overview/actions-and-reducer.mdx @@ -14,12 +14,6 @@ keywords: - mina archive node --- -:::info - -zkApp programmability is not yet available on the Mina **Mainnet**, but zkApps can now be deployed on the Mina **Devnet**. - -::: - # Actions & Reducer Like events, **actions** are _public_ arbitrary information that are passed along with a zkApp transaction. However, actions give you additional power: you can process previous actions in a smart contract! Under the hood, this is possible because a commitment is stored to the history of dispatched actions on every account -- the **actionState**. It allows you to prove that the actions you process are, in fact, the actions that were dispatched to the same smart contract. @@ -38,7 +32,7 @@ class MyContract extends SmartContract { Contrary to events, actions have only one type per smart contract. This type doesn't have a name. The `actionType` in this example is `Field`. -On a `reducer`, you have two functions: `reducer.dispatch()` and `reducer.reduce()`. +On a `reducer`, you have two functions: `reducer.dispatch()` and `reducer.reduce()`. - "Dispatch" is simple -- like emitting events, it pushes one additional action to your account's action history: @@ -46,7 +40,7 @@ On a `reducer`, you have two functions: `reducer.dispatch()` and `reducer.reduce this.reducer.dispatch(Field(1000)); ``` -- "Reduce" is more involved, but it gives you full power to process actions however it suits your application. It might be easiest to grasp from an example where you have a list of actions and want to find out if one of actions is equal to `1000`. +- "Reduce" is more involved, but it gives you full power to process actions however it suits your application. It might be easiest to grasp from an example where you have a list of actions and want to find out if one of actions is equal to `1000`. In JavaScript, a built-in function on `Array` does this: @@ -60,7 +54,7 @@ However, you can also implement this with `Array.reduce`: let has1000 = array.reduce((acc, x) => acc || x === 1000, false); ``` -In fact, `Array.reduce` is powerful enough to let you do pretty much all of the array processing you can think of. +In fact, `Array.reduce` is powerful enough to let you do pretty much all of the array processing you can think of. With `Reducer.reduce`, an in-SNARK operation is just as powerful: @@ -85,7 +79,7 @@ let { state, actionState } = this.reducer.reduce( ); ``` -The `acc` shown earlier is now `state`; you must pass in the state's type as a parameter and pass in an `actionState` which refers to one particular point in the action's history. +The `acc` shown earlier is now `state`; you must pass in the state's type as a parameter and pass in an `actionState` which refers to one particular point in the action's history. Like `Array.reduce`, `Reducer.reduce` takes a callback that has the signature `(state: S, action: A) => S`, where `S` is the `stateType` and `A` is the `actionType`. It returns the result of applying all the actions, in order, to the initial `state`. In this example, the returned `state` is `Bool(true)` because one of the actions in the list is `Field(1000)`. Reduce also returns the new actionState -- so you can store it to use when you reduce the next batch of actions. One last difference to JavaScript `reduce` is that it takes a _list of lists_ of actions, instead of a flat list. Each of the sublists are the actions that were dispatched in one account update (for example, while running one smart contract method). diff --git a/docs/zkapps/writing-a-zkapp/feature-overview/custom-tokens.mdx b/docs/zkapps/writing-a-zkapp/feature-overview/custom-tokens.mdx index 0d32281c9..292315156 100644 --- a/docs/zkapps/writing-a-zkapp/feature-overview/custom-tokens.mdx +++ b/docs/zkapps/writing-a-zkapp/feature-overview/custom-tokens.mdx @@ -17,27 +17,21 @@ keywords: - tokencontract --- -:::info - -zkApp programmability is not yet available on the Mina **Mainnet**, but zkApps can now be deployed on the Mina **Devnet**. - -::: - # Custom Tokens Blockchain applications have various use cases for custom tokens, including a real-world financial asset, stake in an on-chain protocol, or even skill points in a game. Most blockchains, like Ethereum, do not natively support custom tokens. You implement custom tokens as smart contracts on top of the execution layer of the underlying protocol. Token standards ensure the interoperability of applications on Etherum, these standardisations are agree upon in ERCs, Ethereum Request for customElements, such as the fungible token standard [ERC-20](https://ethereum.org/en/developers/docs/standards/tokens/erc-20/). -The Ethereum community has created and agreed upon other reference implementations and standardisation that are audited and easy to configure, such as [ERC-721](https://ethereum.org/en/developers/docs/standards/tokens/erc-721/) for NFTs. +The Ethereum community has created and agreed upon other reference implementations and standardisation that are audited and easy to configure, such as [ERC-721](https://ethereum.org/en/developers/docs/standards/tokens/erc-721/) for NFTs. Mina supports custom token functionality at a low level in the tech stack. Mina treats custom tokens almost the same way as the native MINA token. This approach offers the following benefits: - As a developer, you do not have to manage as many boilerplate contracts. - Developers don't need to keep track of accounts and balances themselves. -- It is more secure because fewer vulnerabilities can result from incorrect configuration and deployment. +- It is more secure because fewer vulnerabilities can result from incorrect configuration and deployment. -Each account on Mina can have tokens associated with it. With zkApps, you build smart contracts that interact with tokens, such as swapping one token for another or depositing MINA tokens. A token manager smart contract is a standard smart contract with the `TokenContract` class that manipulates tokens. +Each account on Mina can have tokens associated with it. With zkApps, you build smart contracts that interact with tokens, such as swapping one token for another or depositing MINA tokens. A token manager smart contract is a standard smart contract with the `TokenContract` class that manipulates tokens. ## Token manager account @@ -51,12 +45,12 @@ A token manager smart contract sets the rules around minting, burning, and sendi ## TokenContract class -Use the `TokenContract` class to perform common token operations, such as minting, burning, and sending tokens. In o1js, the `TokenContract` class is your blueprint for custom token implementations. +Use the `TokenContract` class to perform common token operations, such as minting, burning, and sending tokens. In o1js, the `TokenContract` class is your blueprint for custom token implementations. As shown in this [example code](https://github.com/o1-labs/o1js/blob/main/src/lib/mina/token/token-contract.unit-test.ts#L13), you inherit from the `TokenContract` class: ```ts -class ExampleTokenContract extends TokenContract { +class ExampleTokenContract extends TokenContract { // your custom token implementation } ``` @@ -118,7 +112,7 @@ The usual implementation is as easy as this: However, if you want to do a custom implementation for every child account update, you can utilize the `forEachUpdate()` method. ```ts -@method async +@method async approveBase(updates: AccountUpdateForest) { let totalBalanceChange = Int64.zero; @@ -186,11 +180,11 @@ Token ids are derived from a zkApp. To check the token id of a zkApp, use the `t ### Token Accounts -Token accounts are like regular accounts, but they hold a balance of a specific custom token instead of MINA. A token account is created from an existing account and is specified by a public key _and_ a token id. +Token accounts are like regular accounts, but they hold a balance of a specific custom token instead of MINA. A token account is created from an existing account and is specified by a public key _and_ a token id. Token accounts are specific for each type of custom token, so a single public key can have many different token accounts. -A token account is automatically created for a public key whenever an existing account receives a transaction denoted with a custom token. +A token account is automatically created for a public key whenever an existing account receives a transaction denoted with a custom token. When a token account is created for the first time, an account creation fee must be paid the same as creating a new standard account. @@ -203,4 +197,3 @@ A token owner is an zkApp account that creates, facilitates, and governs how a c - Mint tokens - Burn tokens - Approve sending tokens between two accounts - diff --git a/docs/zkapps/writing-a-zkapp/feature-overview/events.mdx b/docs/zkapps/writing-a-zkapp/feature-overview/events.mdx index 672d2716d..00982d1e0 100644 --- a/docs/zkapps/writing-a-zkapp/feature-overview/events.mdx +++ b/docs/zkapps/writing-a-zkapp/feature-overview/events.mdx @@ -15,12 +15,6 @@ keywords: - transaction --- -:::info - -zkApp programmability is not yet available on the Mina **Mainnet**, but zkApps can now be deployed on the Mina **Devnet**. - -::: - # Events Events are _public_ arbitrary information that can be passed along with a transaction. If your zkApp allows users to publish a message, for example, those messages could be events. @@ -58,7 +52,7 @@ class MyContract extends SmartContract { Some important facts about events: -- Events are not stored on-chain. Only events from the most recent couple of transactions are retained by consensus nodes. After that, the events are discarded, but are still accessible on archive nodes. +- Events are not stored on-chain. Only events from the most recent couple of transactions are retained by consensus nodes. After that, the events are discarded, but are still accessible on archive nodes. - You can't refer to previously emitted events in a smart contract, because there is no way of proving that the events you refer to are actually the events emitted by that contract. :::tip @@ -78,4 +72,3 @@ class SmartContract { emitEvent(name: string, event: any): void; } ``` - diff --git a/docs/zkapps/writing-a-zkapp/feature-overview/fetch-events-and-actions.mdx b/docs/zkapps/writing-a-zkapp/feature-overview/fetch-events-and-actions.mdx index 82db2d924..148bc2e21 100644 --- a/docs/zkapps/writing-a-zkapp/feature-overview/fetch-events-and-actions.mdx +++ b/docs/zkapps/writing-a-zkapp/feature-overview/fetch-events-and-actions.mdx @@ -15,12 +15,6 @@ keywords: - blockchain --- -:::info - -zkApp programmability is not yet available on the Mina **Mainnet**, but zkApps can now be deployed on the Mina **Devnet**. - -::: - # How to Fetch Events and Actions [Events](#events) and [Actions](#actions-and-reducer) are two distinct mechanisms for logging information alongside a transaction: @@ -109,9 +103,9 @@ const fetchedEvents = await fetchEvents({ }); ``` -By default, `fetchEvents()` retrieves all events from the very first event ever emitted for that zkApp account. Additionally, you can provide a starting block height and an ending block height as optional parameters to limit the range of events fetched. +By default, `fetchEvents()` retrieves all events from the very first event ever emitted for that zkApp account. Additionally, you can provide a starting block height and an ending block height as optional parameters to limit the range of events fetched. -- If the ending block is not provided, `fetchEvents()` fetches all events up to the latest block. +- If the ending block is not provided, `fetchEvents()` fetches all events up to the latest block. - If the starting block is not provided, it fetches all events from the beginning of the zkApp's history. To see an end-to-end example of zkApp fetching events from a running network, see the [example](https://github.com/o1-labs/o1js/blob/main/src/examples/zkapps/voting/run-berkeley.ts) file that is provided in the codebase repo. diff --git a/docs/zkapps/writing-a-zkapp/feature-overview/offchain-storage.mdx b/docs/zkapps/writing-a-zkapp/feature-overview/offchain-storage.mdx index ea30fb60c..40b1a716b 100644 --- a/docs/zkapps/writing-a-zkapp/feature-overview/offchain-storage.mdx +++ b/docs/zkapps/writing-a-zkapp/feature-overview/offchain-storage.mdx @@ -15,12 +15,6 @@ keywords: - succinctness --- -:::info - -zkApp programmability is not yet available on the Mina **Mainnet**, but zkApps can now be deployed on the Mina **Devnet**. - -::: - :::experimental Offchain storage is currently an experimental feature and is subject to change in the future. @@ -152,10 +146,10 @@ class MyContract extends SmartContract { }); // retrieve an entry from the map, returning an Option - let playerOption = await offchainState.fields.players.get(playerA); + let playerOption = await offchainState.fields.players.get(playerA); // unwrap the player's score Option and return a default value if the entry is empty - let score = playerOption.orElse(0n); + let score = playerOption.orElse(0n); // increment the player's score, set a precondition on the previous score offchainState.fields.players.update(playerA, { diff --git a/docs/zkapps/writing-a-zkapp/feature-overview/on-chain-values.mdx b/docs/zkapps/writing-a-zkapp/feature-overview/on-chain-values.mdx index 3f9b38a23..c6e859d44 100644 --- a/docs/zkapps/writing-a-zkapp/feature-overview/on-chain-values.mdx +++ b/docs/zkapps/writing-a-zkapp/feature-overview/on-chain-values.mdx @@ -13,12 +13,6 @@ keywords: - network state --- -:::info - -zkApp programmability is not yet available on the Mina **Mainnet**, but zkApps can now be deployed on the Mina **Devnet**. - -::: - # On-Chain Values In a zkApp, you can access the current [on-chain state](/zkapps/writing-a-zkapp/introduction-to-zkapps/how-to-write-a-zkapp#on-chain-state) and many other on-chain values of the account. diff --git a/docs/zkapps/writing-a-zkapp/feature-overview/permissions.mdx b/docs/zkapps/writing-a-zkapp/feature-overview/permissions.mdx index 23ff72445..f175f0e29 100644 --- a/docs/zkapps/writing-a-zkapp/feature-overview/permissions.mdx +++ b/docs/zkapps/writing-a-zkapp/feature-overview/permissions.mdx @@ -15,12 +15,6 @@ keywords: - authorization --- -:::info - -zkApp programmability is not yet available on the Mina **Mainnet**, but zkApps can now be deployed on the Mina **Devnet**. - -::: - # Permissions Permissions are an integral part of zkApp development because they determine who has the authority to interact and make changes to a specific part of a smart contract. @@ -153,9 +147,9 @@ class UnsecureContract extends SmartContract { } ``` -This `UnsecureContract` has only the `withdraw()` method for withdrawing funds from the smart contract account. +This `UnsecureContract` has only the `withdraw()` method for withdrawing funds from the smart contract account. -But first, notice that the permissions specified in the `init()` method have set the `send` permission to `Permissions.none()`. Because `none` means you don't have to provide _any_ form of authorization, a malicious actor can easily drain all funds from the smart contract. +But first, notice that the permissions specified in the `init()` method have set the `send` permission to `Permissions.none()`. Because `none` means you don't have to provide _any_ form of authorization, a malicious actor can easily drain all funds from the smart contract. Take a look at the following malicious transaction that abuses this permission: @@ -194,7 +188,7 @@ await tx.sign([account1Key, zkappKey]).send(); Now that you have provided a valid signature, the transaction succeeds. -However, this way of authorizing a transaction is not what you expect from a smart contract. If you set a permission to `signature`, only the owner of the zkApp's private key (`zkappKey`) is able to perform the interaction. However, the point of a smart contract is to let anyone interact by trustlessly executing the smart contract code. +However, this way of authorizing a transaction is not what you expect from a smart contract. If you set a permission to `signature`, only the owner of the zkApp's private key (`zkappKey`) is able to perform the interaction. However, the point of a smart contract is to let anyone interact by trustlessly executing the smart contract code. For enabling a trustless execution, use `Permissions.proof()`. @@ -222,7 +216,7 @@ If you try running one of the two transactions from before, which created accoun Setting the `send` permission to `proof` means that, to send MINA from this account, you need to execute one of the contract's `@method`. -The contract already has an `@method` that you can use: `withdraw()`. +The contract already has an `@method` that you can use: `withdraw()`. To create a withdrawal transaction that contains a valid proof: @@ -235,11 +229,11 @@ await tx.prove(); await tx.sign([account1Key, zkappKey]).send(); ``` -In contrast to the other examples, you don't explicitly create an `AccountUpdate`. Instead, you instantiate `UnsecureContract` and call its `withdraw()` method. Each method call is automatically associated with an account update, for which it creates a valid proof. You can access and modify this account update by using `this` inside the method. +In contrast to the other examples, you don't explicitly create an `AccountUpdate`. Instead, you instantiate `UnsecureContract` and call its `withdraw()` method. Each method call is automatically associated with an account update, for which it creates a valid proof. You can access and modify this account update by using `this` inside the method. In this example, use `this.send(...)` to send MINA. By calling the method and doing `tx.prove()`, you satisfy the `proof` authorization requirement for sending MINA. -You might have noticed that the contract is still not very secure: Anyone can call the `withdraw()` method to drain any amount of MINA from the contract. That's why the example is called `UnsecureContract`. +You might have noticed that the contract is still not very secure: Anyone can call the `withdraw()` method to drain any amount of MINA from the contract. That's why the example is called `UnsecureContract`. In a real contract, you would add some conditions to the `withdraw()` code to restrict which users can successfully call the method. @@ -265,12 +259,12 @@ Recall that the `Impossible` permission prevents the verification key from being Internally, verification key permissions are represented as a tuple of two fields: the mechanism that controls verification key changes (e.g. `Impossible`, `Signature`, `Proof`), and a transaction version field (denoted by an integer). The transaction version field specifies the version of a transaction that was supported by the protocol when the zkApp's verification key was -deployed. This allows the protocol to appropriately enforce permissions when a zkApps was deployed on an earlier version that may no longer be supported. +deployed. This allows the protocol to appropriately enforce permissions when a zkApps was deployed on an earlier version that may no longer be supported. To allow zkApps to upgrade their verification key after a protocol upgrade, the `Impossible` and `Proof` verification key permissions are automatically treated as `Signature` permissions when the zkApp's transaction version is lower than the current one on Mina Protocol. This allows zkApps to upgrade their verification key after a protocol upgrade, even if the permission was originally set to `Impossible` or `Proof`. -Thus, `setVerificationKey` field behaves slightly different and requires two properties. +Thus, `setVerificationKey` field behaves slightly different and requires two properties. ```ts setVerificationKey: { diff --git a/docs/zkapps/writing-a-zkapp/feature-overview/time-locked-accounts.mdx b/docs/zkapps/writing-a-zkapp/feature-overview/time-locked-accounts.mdx index b5704dcce..50c98a294 100644 --- a/docs/zkapps/writing-a-zkapp/feature-overview/time-locked-accounts.mdx +++ b/docs/zkapps/writing-a-zkapp/feature-overview/time-locked-accounts.mdx @@ -12,12 +12,6 @@ keywords: - account timing --- -:::info - -zkApp programmability is not yet available on the Mina **Mainnet**, but zkApps can now be deployed on the Mina **Devnet**. - -::: - # Time-Locked Accounts Time-locking allows you to pay someone in MINA or other custom tokens subject to a vesting schedule. Tokens are initially locked and become available for withdrawal only after a certain time or gradually according to a specific schedule. @@ -41,7 +35,7 @@ type Account = { ``` - The `isTimed` field indicates whether this account is time-locked. The default value of `isTimed` is `false`. -- The other fields are parameters with default values that allow you to define a vesting schedule in a very flexible manner. +- The other fields are parameters with default values that allow you to define a vesting schedule in a very flexible manner. This graph shows how each of the timing properties affect the vesting schedule: @@ -54,8 +48,8 @@ This graph shows how each of the timing properties affect the vesting schedule: - The red cross on the left marks the point in time where the `timing` field is set. -- `isTimed` switches from `false` to `true`. -- The orange line shows how the amount of unlocked tokens increases over time until it finally reaches its maximum value and stays flat. +- `isTimed` switches from `false` to `true`. +- The orange line shows how the amount of unlocked tokens increases over time until it finally reaches its maximum value and stays flat. - At this point, `isTimed` flips from `true` back to `false` because no tokens remain locked. As shown, the maximum amount of unlocked tokens is defined by the `initialMinimumBalance`. The property is called `initialMinimumBalance` because, even though the tokens show up in the balance, they can't be withdrawn. The account has a a non-zero _minimum balance_. Initially, that minimum balance is equal to the amount of tokens locked -- so, that amount is the "initial minimum balance". Over time, the minimum balance decreases until it hits zero, which is the condition that makes `isTimed` false again. @@ -90,9 +84,9 @@ These examples show how to correctly implement several example use cases. #### Example 1: All tokens unlock after 1 week -If you want all tokens to unlock after a certain time, then the only properties you need to consider are `initialMinimumBalance`, `cliffTime`, and `cliffAmount`. +If you want all tokens to unlock after a certain time, then the only properties you need to consider are `initialMinimumBalance`, `cliffTime`, and `cliffAmount`. -- Set `cliffAmount` equal to the `initialMinimumBalance` to ensure all tokens are unlocked when the cliff elapses. +- Set `cliffAmount` equal to the `initialMinimumBalance` to ensure all tokens are unlocked when the cliff elapses. - Both `vestingPeriod` and `vestingIncrement` are unused, so set them to their default values, `1` and `0`: ```ts @@ -115,10 +109,10 @@ If you want all tokens to unlock after a certain time, then the only properties #### Example 2: Linear vesting over 1 year -This example does not use a cliff, but vests a certain number of tokens linearly over 1 year. +This example does not use a cliff, but vests a certain number of tokens linearly over 1 year. -- Set the `vestingPeriod` to equivalent to 1 month defined in slots, so that new tokens are unlocked every month. -- Set the `vestingIncrement` to the total amount divided by 12, so that the total amount is unlocked after 12 months. +- Set the `vestingPeriod` to equivalent to 1 month defined in slots, so that new tokens are unlocked every month. +- Set the `vestingIncrement` to the total amount divided by 12, so that the total amount is unlocked after 12 months. - Set both `cliffTime` and `cliffAmount` to 0. ```ts diff --git a/docs/zkapps/writing-a-zkapp/index.mdx b/docs/zkapps/writing-a-zkapp/index.mdx index 97ccbd200..353c7f410 100644 --- a/docs/zkapps/writing-a-zkapp/index.mdx +++ b/docs/zkapps/writing-a-zkapp/index.mdx @@ -13,12 +13,6 @@ keywords: - quickstart zkapps --- -:::info - -zkApp programmability is not yet available on the Mina **Mainnet**, but zkApps can now be deployed on the Mina **Devnet**. - -::: - # zkApps Overview
@@ -91,4 +85,4 @@ Try the [zkApps tutorials](/zkapps/tutorials/hello-world) to learn by doing! ### Get help and join the community -Join the [#zkapps-developers](https://discord.com/channels/484437221055922177/915745847692636181) channel on Mina Protocol Discord. +Join the [#zkapps-developers](https://discord.com/channels/484437221055922177/915745847692636181) channel on Mina Protocol Discord. diff --git a/docs/zkapps/writing-a-zkapp/introduction-to-zkapps/getting-started-zkapps.mdx b/docs/zkapps/writing-a-zkapp/introduction-to-zkapps/getting-started-zkapps.mdx index be89b595a..ab49e779c 100644 --- a/docs/zkapps/writing-a-zkapp/introduction-to-zkapps/getting-started-zkapps.mdx +++ b/docs/zkapps/writing-a-zkapp/introduction-to-zkapps/getting-started-zkapps.mdx @@ -13,12 +13,6 @@ keywords: - quickstart zkapps --- -:::info - -zkApp programmability is not yet available on the Mina **Mainnet**, but zkApps can now be deployed on the Mina **Devnet**. - -::: - # zkApps Getting Started You can start writing zkApps with just a few steps. The focus of this Getting Started Guide is a high-level workflow to build and deploy quickly. @@ -50,21 +44,21 @@ See [zkApp CLI Installation](/zkapps/writing-a-zkapp/introduction-to-zkapps/inst $ zk project ``` -[o1js](/zkapps/o1js) is automatically installed when you generate a project using the zkApp CLI. +[o1js](/zkapps/o1js) is automatically installed when you generate a project using the zkApp CLI. -A zkApp consists of a smart contract and a UI to interact with it. +A zkApp consists of a smart contract and a UI to interact with it. - To proceed without an accompanying UI project, select `none` when prompted. See [Option B: Start your own project](/zkapps/writing-a-zkapp/introduction-to-zkapps/how-to-write-a-zkapp#option-b-start-your-own-project). -- To create a UI, select a framework and follow the prompts. +- To create a UI, select a framework and follow the prompts. See [How to Write a zkApp UI](/zkapps/writing-a-zkapp/introduction-to-zkapps/how-to-write-a-zkapp-ui). ### 3. Add testing code -When you use the zkApp CLI to create a project, tests and examples are included. +When you use the zkApp CLI to create a project, tests and examples are included. 1. See the `import` statements in the [Add.test.ts](https://github.com/o1-labs/zkapp-cli/blob/main/templates/project-ts/src/Add.test.ts#L1-L2) example file. @@ -112,7 +106,7 @@ Add the logic for your smart contract. ### 7. Test with Lightnet -- Use [Lightnet](zkapps/writing-a-zkapp/introduction-to-zkapps/testing-zkapps-lightnet) to test your zkApp with an accurate representation of Mina blockchain. +- Use [Lightnet](zkapps/writing-a-zkapp/introduction-to-zkapps/testing-zkapps-lightnet) to test your zkApp with an accurate representation of Mina blockchain. 1. Start Lightnet: @@ -130,7 +124,7 @@ Add the logic for your smart contract. 1. Communicate with the Mina Accounts-Manager service to fetch account details. - - Mina Accounts-Manager is deployed to http://localhost:8181/ + - Mina Accounts-Manager is deployed to http://localhost:8181/ - Use HTTP endpoints to acquire, release, list, lock, and unlock accounts 1. Configure your zkApp for Lightnet blockchain. Use the endpoints provided by the `zk lightnet status` command. @@ -147,7 +141,7 @@ Add the logic for your smart contract. ### 8. Test with a live network -To deploy the smart contract to the Testnet, run the `zk` commands from the directory that contains your smart contract. +To deploy the smart contract to the Testnet, run the `zk` commands from the directory that contains your smart contract. 1. Configure your zkApp. @@ -155,18 +149,18 @@ To deploy the smart contract to the Testnet, run the `zk` commands from the dire zk config ``` - Follow the prompts to specify a deploy alias name (can be anything), URL to deploy to, fee (in MINA) to be used when sending your deploy transaction, and the fee payer account. + Follow the prompts to specify a deploy alias name (can be anything), URL to deploy to, fee (in MINA) to be used when sending your deploy transaction, and the fee payer account. For the Devnet, use: - - - Deploy alias name: `devnet` - + + - Deploy alias name: `devnet` + - Mina GraphQL API URL: `https://api.minascan.io/node/devnet/v1/graphql` - + - Transaction fee to use when deploying: `0.1` - + - Account to pay transaction fees: Create a new fee payer pair - + See [Add a deploy alias to config.json](/zkapps/writing-a-zkapp/introduction-to-zkapps/how-to-deploy-a-zkapp#add-a-deploy-alias-to-configjson). For other Testnets, use the details provided. @@ -188,27 +182,27 @@ To deploy the smart contract to the Testnet, run the `zk` commands from the dire The option to choose another account is shown only if you have a cached fee payer account. - - Next, select **Create a new fee payer key pair**: + - Next, select **Create a new fee payer key pair**: ```sh Create a new fee payer key pair NOTE: the private key will be stored in plain text on this computer. ``` - - When prompted, give an alias to your new fee payer key pair. + - When prompted, give an alias to your new fee payer key pair. 1. Fund your fee payer account. - Follow the prompts to request tMina. + Follow the prompts to request tMina. -1. Deploy to the Testnet. +1. Deploy to the Testnet. ```sh zk deploy ``` - Follow the prompts. - + Follow the prompts. + See [How to deploy a zkApp](/zkapps/writing-a-zkapp/introduction-to-zkapps/how-to-deploy-a-zkapp). 1. Create a script to interact with a live network. @@ -235,4 +229,4 @@ Try the [zkApp Developer Tutorials](/zkapps/tutorials) for use cases that guide ## Get help and join the community -Join the [#zkapps-developers](https://discord.com/channels/484437221055922177/915745847692636181) channel on Mina Protocol Discord. \ No newline at end of file +Join the [#zkapps-developers](https://discord.com/channels/484437221055922177/915745847692636181) channel on Mina Protocol Discord. diff --git a/docs/zkapps/writing-a-zkapp/introduction-to-zkapps/how-to-deploy-a-zkapp.mdx b/docs/zkapps/writing-a-zkapp/introduction-to-zkapps/how-to-deploy-a-zkapp.mdx index 1dad9b345..3588c5e9a 100644 --- a/docs/zkapps/writing-a-zkapp/introduction-to-zkapps/how-to-deploy-a-zkapp.mdx +++ b/docs/zkapps/writing-a-zkapp/introduction-to-zkapps/how-to-deploy-a-zkapp.mdx @@ -9,15 +9,9 @@ keywords: - configure a zkapp --- -:::info - -zkApp programmability is not yet available on the Mina **Mainnet**, but zkApps can now be deployed on the Mina **Devnet**. - -::: - # How to Deploy a zkApp -Before deploying, you must first define a few settings, such as which network you are deploying your zkApp to. +Before deploying, you must first define a few settings, such as which network you are deploying your zkApp to. ## Add a deploy alias to config.json @@ -35,7 +29,7 @@ When prompted, specify: - Transaction fee (in MINA) to use when deploying - The fee payer account to pay transaction fees from -For more details, see [deploy alias](/zkapps/tutorials/deploying-to-a-network#deploy-alias) section in corresponding tutorial. +For more details, see [deploy alias](/zkapps/tutorials/deploying-to-a-network#deploy-alias) section in corresponding tutorial. :::tip If your project contains multiple smart contracts (for example, `Foo` and `Bar`) that @@ -131,8 +125,8 @@ Next step: https://minascan.io/devnet/tx/?type=zk-tx ``` -After a few minutes, the transaction is included in the next block. -To see the zkApp transaction and navigate to accounts involved you can follow the transaction link provided to you in zkApp CLI output. +After a few minutes, the transaction is included in the next block. +To see the zkApp transaction and navigate to accounts involved you can follow the transaction link provided to you in zkApp CLI output. Or use the [Minascan](https://minascan.io) explorer to search for the account with deployed zkApp. ## Next Steps diff --git a/docs/zkapps/writing-a-zkapp/introduction-to-zkapps/how-to-write-a-zkapp-ui.mdx b/docs/zkapps/writing-a-zkapp/introduction-to-zkapps/how-to-write-a-zkapp-ui.mdx index 3e9c7068b..684429a9a 100644 --- a/docs/zkapps/writing-a-zkapp/introduction-to-zkapps/how-to-write-a-zkapp-ui.mdx +++ b/docs/zkapps/writing-a-zkapp/introduction-to-zkapps/how-to-write-a-zkapp-ui.mdx @@ -13,12 +13,6 @@ keywords: - Auro Wallet --- -:::info - -zkApp programmability is not yet available on the Mina **Mainnet**, but zkApps can now be deployed on the Mina **Devnet**. - -::: - # How to Write a zkApp UI A zkApp consists of a smart contract and a UI to interact with it. To allow users to interact with your smart contract in a web browser, you typically want to build a website UI. @@ -27,13 +21,13 @@ You can write the UI with any framework like React, Vue, or Svelte, or with plai ## Using one of the provided UI framework scaffolds -When you create a project using the zkApp CLI, you can choose a supported UI framework to be scaffolded as a part of your zkApp project. For example, Next.js, Sveltkit, or Nuxt.js. +When you create a project using the zkApp CLI, you can choose a supported UI framework to be scaffolded as a part of your zkApp project. For example, Next.js, Sveltkit, or Nuxt.js. ## Adding your smart contract as a dependency of the UI You can use one of the provided scaffolding options and add your smart contract to an existing frontend, a different UI framework, or a plain HTML and JavaScript website. -### Specify the smart contracts to import +### Specify the smart contracts to import The `index.ts` file is the entry point of your project that imports all smart contract classes you want access to and exports them to your smart contract. This pattern allows you to specify which smart contracts are available to import when consuming your project from npm within your UI. @@ -47,7 +41,7 @@ export { YourSmartContract }; ### Local development -To test iteratively and use your smart contract within your UI project during local development, you can use [npm link](https://docs.npmjs.com/cli/v8/commands/npm-link). This local use allows for rapid development without having to publish your project to npm. +To test iteratively and use your smart contract within your UI project during local development, you can use [npm link](https://docs.npmjs.com/cli/v8/commands/npm-link). This local use allows for rapid development without having to publish your project to npm. 1. To change into your smart contract project directory: @@ -61,10 +55,10 @@ To test iteratively and use your smart contract within your UI project during lo npm link ``` - where `your-package-name` is the `name` property used in your _smart contract's_ `package.json`. + where `your-package-name` is the `name` property used in your _smart contract's_ `package.json`. + + For example, the `name` property in `package.json` for the `sudoku` example project that you created in [How to Write a zkApp](/zkapps/writing-a-zkapp/introduction-to-zkapps/how-to-write-a-zkapp) is `sudoku`. - For example, the `name` property in `package.json` for the `sudoku` example project that you created in [How to Write a zkApp](/zkapps/writing-a-zkapp/introduction-to-zkapps/how-to-write-a-zkapp) is `sudoku`. - To create the symlinks for `sudoku`: ```sh @@ -93,11 +87,11 @@ To test iteratively and use your smart contract within your UI project during lo ### Publish to npm for production -1. Create an npm account. +1. Create an npm account. If you don't already have an account, go to npm [Sign Up](https://www.npmjs.com/signup). -1. Login to npm: +1. Login to npm: ```sh npm login @@ -113,7 +107,7 @@ To test iteratively and use your smart contract within your UI project during lo Package names must be unique. An error occurs if the package name already exists. To use a different package name, change the `name` property in the `package.json` file. -To check existing package names on npm, use the [npm search](https://docs.npmjs.com/cli/v7/commands/npm-search) command. +To check existing package names on npm, use the [npm search](https://docs.npmjs.com/cli/v7/commands/npm-search) command. To avoid naming collisions, npm allows you to publish scoped packages: `@your-username/your-package-name`. See [Introduction to packages and modules](https://docs.npmjs.com/packages-and-modules/introduction-to-packages-and-modules) in the npm reference docs. @@ -125,7 +119,7 @@ After you have published your smart contract to npm, you can add it to any UI fr ```sh npm install your-package-name - ``` + ``` If you published a scoped npm package: @@ -138,7 +132,7 @@ After you have published your smart contract to npm, you can add it to any UI fr ```ts import { YourSmartContract } from ‘your-package-name’; ``` - + where `YourSmartContract` is the named export that you chose in your smart contract. :::tip @@ -178,7 +172,7 @@ onMounted(async () => { ### Enabling COOP and COEP headers To load o1js code in your UI, you must set the [COOP](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cross-Origin-Opener-Policy) -and [COEP](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cross-Origin-Embedder-Policy) headers. +and [COEP](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cross-Origin-Embedder-Policy) headers. These headers enable o1js to use [SharedArrayBuffer](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/SharedArrayBuffer) that o1js relies on to enable important WebAssembly (Wasm) features. @@ -217,18 +211,18 @@ To host your app on Cloudflare Pages, set the headers in a [`_headers` file](htt ### Connecting your zkApp with a user's wallet -The Mina community has created a variety of different wallets. Only the [Auro Wallet for Chrome](https://www.aurowallet.com) supports interactions with zkApps. +The Mina community has created a variety of different wallets. Only the [Auro Wallet for Chrome](https://www.aurowallet.com) supports interactions with zkApps. To interact with your zkApp, users of your zkApp must have the Auro Wallet installed: -- `window.mina` is automatically available in the user's browser environment. +- `window.mina` is automatically available in the user's browser environment. - Your zkApp uses this object to interact with the wallet. -1. Install the Chrome extension for [Auro Wallet](https://chrome.google.com/webstore/detail/auro-walletmina-protocol/cnmamaachppnkjgnildpdmkaakejnhae). +1. Install the Chrome extension for [Auro Wallet](https://chrome.google.com/webstore/detail/auro-walletmina-protocol/cnmamaachppnkjgnildpdmkaakejnhae). -2. Get accounts. +2. Get accounts. - To fetch a user's list of Mina accounts, use the `requestAccounts()` method: + To fetch a user's list of Mina accounts, use the `requestAccounts()` method: ```ts let accounts; @@ -250,7 +244,7 @@ To interact with your zkApp, users of your zkApp must have the Auro Wallet insta -3. Send a transaction. +3. Send a transaction. After your user interacts with your zkApp, you can sign and send the transaction using `sendTransaction()`. You receive a transaction ID as soon as the Mina network has received the proposed transaction. However, this does not guarantee that the transaction is accepted in the network into an upcoming block. diff --git a/docs/zkapps/writing-a-zkapp/introduction-to-zkapps/how-to-write-a-zkapp.mdx b/docs/zkapps/writing-a-zkapp/introduction-to-zkapps/how-to-write-a-zkapp.mdx index a6344b5e1..dc52ed1aa 100644 --- a/docs/zkapps/writing-a-zkapp/introduction-to-zkapps/how-to-write-a-zkapp.mdx +++ b/docs/zkapps/writing-a-zkapp/introduction-to-zkapps/how-to-write-a-zkapp.mdx @@ -11,17 +11,11 @@ keywords: - zero knowledge proofs --- -:::info - -zkApp programmability is not yet available on the Mina **Mainnet**, but zkApps can now be deployed on the Mina **Devnet**. - -::: - # How to Write a zkApp -A zkApp consists of a smart contract and a UI to interact with it. +A zkApp consists of a smart contract and a UI to interact with it. -Write your smart contract using the [zkApp CLI](https://www.npmjs.com/package/zkapp-cli/). +Write your smart contract using the [zkApp CLI](https://www.npmjs.com/package/zkapp-cli/). First, install the zkApp CLI: @@ -29,13 +23,13 @@ First, install the zkApp CLI: npm install -g zkapp-cli ``` -See [zkApp CLI Installation](/zkapps/writing-a-zkapp/introduction-to-zkapps/install-zkapp-cli). +See [zkApp CLI Installation](/zkapps/writing-a-zkapp/introduction-to-zkapps/install-zkapp-cli). ## Start a project Now that you have the zkApp CLI installed, you can start with an example or create your own project. -Example projects do not create an accompanying UI. +Example projects do not create an accompanying UI. ### Option A: Start with an example (recommended) @@ -55,39 +49,39 @@ Examples are based on the standard project structure and provide additional file tictactoe ``` - Select the `sudoku` example project. + Select the `sudoku` example project. + + The created project includes the example files (the smart contract) and the example test files in the project's `src` directory. - The created project includes the example files (the smart contract) and the example test files in the project's `src` directory. - 1. View the files that were created: - Change to the `sudoku` directory. - Run the `ls` command - + Or open the directory in a code editor, such as VS Code. -1. This example zkApp includes the `sudoku.test.ts` test file. To run tests and see the tests pass: +1. This example zkApp includes the `sudoku.test.ts` test file. To run tests and see the tests pass: ```sh npm run test ``` - + To rerun tests automatically after you save changes to your code, you can run the tests in watch mode: ```sh npm run testw ``` - -1. Now that you have confirmed that tests run correctly, you can compile your TypeScript into JavaScript in the project `/build` directory. + +1. Now that you have confirmed that tests run correctly, you can compile your TypeScript into JavaScript in the project `/build` directory. To build the example: ```sh npm run build ``` - + - The `npm run build` command builds the TypeScript files in `sudoku/src` that contain the code for the smart contract. - - This build command compiles the TypeScript code into JavaScript in the `sudoku/build` directory. + - This build command compiles the TypeScript code into JavaScript in the `sudoku/build` directory. 1. Configure your zkApp: @@ -95,36 +89,36 @@ Examples are based on the standard project structure and provide additional file zk config ``` - The command prompts guide you to add a deploy alias to your project `config.json` file. - -1. Define a name for the deploy alias. + The command prompts guide you to add a deploy alias to your project `config.json` file. + +1. Define a name for the deploy alias. For this example, use: - + ```text devnet - ``` - + ``` + The deploy alias name does not have to match the network name. 1. Choose the target network kind: ```text Testnet - ``` - - 1. Set the Mina GraphQL API URL to deploy to: + ``` + + 1. Set the Mina GraphQL API URL to deploy to: ```text https://api.minascan.io/node/devnet/v1/graphql - ``` + ``` 1. Set the transaction fee to use when deploying: ```text 0.1 - ``` - + ``` + 1. When prompted to choose an account to pay transaction fees, select: ```text @@ -140,7 +134,7 @@ Examples are based on the standard project structure and provide additional file The option to choose another account is shown only if you have a cached fee payer account. -1. Select to create a new fee payer key pair: +1. Select to create a new fee payer key pair: ```sh Create a new fee payer key pair @@ -167,28 +161,28 @@ Examples are based on the standard project structure and provide additional file zk deploy ``` - Follow the prompts to select the `devnet` deploy alias and confirm that you want to send the transaction. - + Follow the prompts to select the `devnet` deploy alias and confirm that you want to send the transaction. + Your smart contract transaction is pending until the transaction is included in a block. -1. To view your transaction, click the block explorer link. +1. To view your transaction, click the block explorer link. - For example: + For example: `https://minascan.io/devnet/tx/?type=zk-tx` - + For details, see [How to Deploy a zkApp](how-to-deploy-a-zkapp). ### Option B: Start your own project -Instead of using a provided example, you can follow these steps to create your own project. +Instead of using a provided example, you can follow these steps to create your own project. -1. Create your own project: +1. Create your own project: ```sh zk project ``` - The created project includes the smart contract files in the project's `src/` directory. + The created project includes the smart contract files in the project's `src/` directory. 1. Select an accompanying UI framework, if any: @@ -200,17 +194,17 @@ Instead of using a provided example, you can follow these steps to create your o empty none ``` - + For your selected UI framework, follow the prompts. See [How to Write a zkApp UI](/zkapps/writing-a-zkapp/introduction-to-zkapps/how-to-write-a-zkapp-ui). To see the files that were created, change to the project (whatever you called ``) directory and run the `ls` command or open the directory in a code editor, such as VS Code. -1. When you use the zkApp CLI to create a project, the default `Add` smart contract is included along with the `Add.test.ts` test files. +1. When you use the zkApp CLI to create a project, the default `Add` smart contract is included along with the `Add.test.ts` test files. ```sh npm run test ``` - + To rerun tests automatically after you save changes to your code, you can run the tests in watch mode: ```sh @@ -222,8 +216,8 @@ Instead of using a provided example, you can follow these steps to create your o ```sh npm run build ``` - - The `npm run build` command builds the TypeScript files in `yourproject/src` that contain the code for the smart contract. This build command compiles the TypeScript code into JavaScript in the `yourproject/build` directory. + + The `npm run build` command builds the TypeScript files in `yourproject/src` that contain the code for the smart contract. This build command compiles the TypeScript code into JavaScript in the `yourproject/build` directory. 1. Configure your zkApp: @@ -231,15 +225,15 @@ Instead of using a provided example, you can follow these steps to create your o zk config ``` - The command prompts guide you to add a deploy alias to your project `config.json` file. - + The command prompts guide you to add a deploy alias to your project `config.json` file. + 1. To configure your deploy alias, follow the prompts: - - - Create a (deploy alias) name: _yourprojecttestnet_ - - Choose the target network: `Testnet` - - Set the Mina GraphQL API URL: `https://api.minascan.io/node/devnet/v1/graphql` - - Set transaction fee to use when deploying (in MINA): `0.1` - - Choose an account to pay transaction fees: + + - Create a (deploy alias) name: _yourprojecttestnet_ + - Choose the target network: `Testnet` + - Set the Mina GraphQL API URL: `https://api.minascan.io/node/devnet/v1/graphql` + - Set transaction fee to use when deploying (in MINA): `0.1` + - Choose an account to pay transaction fees: - `Create a new fee payer key pair` - Create an alias for this account: _yourdeployalias_ @@ -247,14 +241,14 @@ Instead of using a provided example, you can follow these steps to create your o 1. Fund your fee payer account. Follow the prompts to request tMina. -1. Deploy to Testnet: +1. Deploy to Testnet: ```sh zk deploy yourprojecttestnet ``` - Follow the prompts. - + Follow the prompts. + To learn more about deploying, see [How to Deploy a zkApp](how-to-deploy-a-zkapp). ## Writing your smart contract @@ -268,13 +262,13 @@ To get started writing zkApps, begin with these o1js docs: A basic smart contract example is generated when you created a zk project. The high-level smart contract code workflow is: -1. Import `o1js`. +1. Import `o1js`. See the `import` statement in the [Add.ts](https://github.com/o1-labs/zkapp-cli/blob/main/templates/project-ts/src/Add.ts#L1) file. 1. Extend the `SmartContract` class. - See the exported `class` in the [Add.ts](https://github.com/o1-labs/zkapp-cli/blob/main/templates/project-ts/src/Add.ts#L12) file. + See the exported `class` in the [Add.ts](https://github.com/o1-labs/zkapp-cli/blob/main/templates/project-ts/src/Add.ts#L12) file. For guided steps to create your first zkApp, start with [Tutorial 1: Hello World](zkapps/tutorials/hello-world). diff --git a/docs/zkapps/writing-a-zkapp/introduction-to-zkapps/how-zkapps-work.mdx b/docs/zkapps/writing-a-zkapp/introduction-to-zkapps/how-zkapps-work.mdx index ec5abc371..3fb94639c 100644 --- a/docs/zkapps/writing-a-zkapp/introduction-to-zkapps/how-zkapps-work.mdx +++ b/docs/zkapps/writing-a-zkapp/introduction-to-zkapps/how-zkapps-work.mdx @@ -14,19 +14,13 @@ keywords: - off-chain state --- -:::info - -zkApp programmability is not yet available on the Mina **Mainnet**, but zkApps can now be deployed on the Mina **Devnet**. - -::: - # How zkApps Work zkApps run in the latest versions of [Chrome](https://www.google.com/chrome/index.html), [Firefox](https://www.mozilla.org/en-US/firefox/new/), [Edge](https://microsoft.com/edge), and [Brave](https://brave.com/) web browsers. -zkApps are written in TypeScript using the zkApp CLI. +zkApps are written in TypeScript using the zkApp CLI. -A zkApp consists of two parts: +A zkApp consists of two parts: - A smart contract @@ -40,11 +34,11 @@ A zkApp consists of two parts: ## Zero knowledge-based smart contracts -zkApps are based on zero knowledge proofs (zk-SNARKs). As a zkApp developer, you use the zkApp CLI to scaffold and deploy your project. +zkApps are based on zero knowledge proofs (zk-SNARKs). As a zkApp developer, you use the zkApp CLI to scaffold and deploy your project. Provable code is written using o1js and generates a prover function and a corresponding verifier function that are derived during the build process. -The prover function is the function that executes a smart contract's custom logic and runs in an end user's web browser as part of the zkApp. The prover function generates a proof of the executed code. +The prover function is the function that executes a smart contract's custom logic and runs in an end user's web browser as part of the zkApp. The prover function generates a proof of the executed code. When interacting with a zkApp UI, users enter any data (for example, buy ABC for y price) that is required as input to the prover function, which then generates a zero knowledge proof. @@ -66,7 +60,7 @@ Within the Mina network, Mina acts as the verifier and runs the verifier functio ## Prover Function and Verification Key -After you write a smart contract, build it by running the `npm run build` command. The build process compiles the TypeScript code into JavaScript and outputs the `smart_contract.js` file. +After you write a smart contract, build it by running the `npm run build` command. The build process compiles the TypeScript code into JavaScript and outputs the `smart_contract.js` file. From this file, you can: @@ -85,9 +79,9 @@ zkApp developers use the zkApp CLI to deploy smart contracts to the Mina network When a Mina address contains a verification key, it acts as a zkApp account. -A regular Mina account can receive any transactions. +A regular Mina account can receive any transactions. -You can specify [permissions](/zkapps/writing-a-zkapp/feature-overview/permissions) so a zkApp account can successfully receive only the transactions that satisfy the verifier function. +You can specify [permissions](/zkapps/writing-a-zkapp/feature-overview/permissions) so a zkApp account can successfully receive only the transactions that satisfy the verifier function. The Mina network rejects any transactions that do not pass the verifier function. @@ -95,7 +89,7 @@ When you deploy a zkApp to a new Mina address, the Mina Protocol charges a 1 MIN ## Deploy a zkApp UI -A zkApp consists of a smart contract and a UI to interact with it. +A zkApp consists of a smart contract and a UI to interact with it. To enable users to interact with your smart contract in a web browser, you build a website UI and then deploy this interactive UI as a static website. Choosing a host that offers a global content delivery network (CDN) ensures the best experience for all users. @@ -116,10 +110,10 @@ After a zkApp is deployed to a host (for example, mycoolzkapp.com), end users ca - Private, the data is never seen by the blockchain. - Public, the data is stored on-chain or off-chain, depending on what the zkApp specified as required for a given use case. - A list of state updates (called account updates) to be created by the transaction is generated. The account updates are associated with this proof. + A list of state updates (called account updates) to be created by the transaction is generated. The account updates are associated with this proof. 1. The user selects **Submit to chain** in the zkApp UI. - - The user confirms the transaction on their wallet. + - The user confirms the transaction on their wallet. - The wallet signs the transaction containing the proof and the associated description of state to update. - The wallet sends the transaction to the Mina network. @@ -137,7 +131,7 @@ The integrity of these account updates is ensured by passing a hash of the accou ### zkApp state -- On-chain state describes state that lives on the Mina blockchain. +- On-chain state describes state that lives on the Mina blockchain. - Off-chain state describes state stored anywhere else. diff --git a/docs/zkapps/writing-a-zkapp/introduction-to-zkapps/install-zkapp-cli.mdx b/docs/zkapps/writing-a-zkapp/introduction-to-zkapps/install-zkapp-cli.mdx index 184cf6670..da15848f8 100644 --- a/docs/zkapps/writing-a-zkapp/introduction-to-zkapps/install-zkapp-cli.mdx +++ b/docs/zkapps/writing-a-zkapp/introduction-to-zkapps/install-zkapp-cli.mdx @@ -1,7 +1,7 @@ --- title: Install zkApp CLI hide_title: true -description: Prerequisites and installation steps for the zkApp CLI. +description: Prerequisites and installation steps for the zkApp CLI. keywords: - zkApp CLI - installation @@ -10,15 +10,9 @@ keywords: - install zkApp CLI --- -:::info - -zkApp programmability is not yet available on the Mina **Mainnet**, but zkApps can now be deployed on the Mina **Devnet**. - -::: - # zkApp CLI Installation -Install and use the zkApp CLI to scaffold, write, test, and deploy zkApps (zero knowledge apps) for Mina Protocol using recommended best practices. +Install and use the zkApp CLI to scaffold, write, test, and deploy zkApps (zero knowledge apps) for Mina Protocol using recommended best practices. :::tip To build zero knowledge apps that use [o1js](/zkapps/o1js), you only need to install the zkApp CLI. o1js is automatically included when you create a project using the zkApp CLI. In the root of your project directory, use `zk system` to show the system information with installed versions of zkApp CLI and o1js. @@ -30,7 +24,7 @@ To build zero knowledge apps that use [o1js](/zkapps/o1js), you only need to ins - NPM v10 and later - git v2 and later -If you have a later version of a dependency, install the required version using the package manager for your system: +If you have a later version of a dependency, install the required version using the package manager for your system: - MacOs [Homebrew](https://brew.sh/) diff --git a/docs/zkapps/writing-a-zkapp/introduction-to-zkapps/interact-with-mina.md b/docs/zkapps/writing-a-zkapp/introduction-to-zkapps/interact-with-mina.md index a4ef2b0ff..858e65d1e 100644 --- a/docs/zkapps/writing-a-zkapp/introduction-to-zkapps/interact-with-mina.md +++ b/docs/zkapps/writing-a-zkapp/introduction-to-zkapps/interact-with-mina.md @@ -19,12 +19,6 @@ keywords: - authorization types --- -:::info - -zkApp programmability is not yet available on the Mina **Mainnet**, but zkApps can now be deployed on the Mina **Devnet**. - -::: - # Interacting With Mina Now that you know about writing zkApp methods, it's time to learn how users can call these methods. diff --git a/docs/zkapps/writing-a-zkapp/introduction-to-zkapps/secure-zkapps.mdx b/docs/zkapps/writing-a-zkapp/introduction-to-zkapps/secure-zkapps.mdx index e8e4e24cd..8619d915e 100644 --- a/docs/zkapps/writing-a-zkapp/introduction-to-zkapps/secure-zkapps.mdx +++ b/docs/zkapps/writing-a-zkapp/introduction-to-zkapps/secure-zkapps.mdx @@ -11,12 +11,6 @@ keywords: - zero knowledge proofs --- -:::info - -zkApp programmability is not yet available on the Mina **Mainnet**, but zkApps can now be deployed on the Mina **Devnet**. - -::: - # Security and zkApps On this page, you will find guidance for how to think about security when building zkApps. We also provide a list of best practices and common pitfalls to help you avoid vulnerabilities. diff --git a/docs/zkapps/writing-a-zkapp/introduction-to-zkapps/smart-contracts.mdx b/docs/zkapps/writing-a-zkapp/introduction-to-zkapps/smart-contracts.mdx index f9d7d18a9..1a7ab479e 100644 --- a/docs/zkapps/writing-a-zkapp/introduction-to-zkapps/smart-contracts.mdx +++ b/docs/zkapps/writing-a-zkapp/introduction-to-zkapps/smart-contracts.mdx @@ -18,12 +18,6 @@ keywords: - on-chain state --- -:::info - -zkApp programmability is not yet available on the Mina **Mainnet**, but zkApps can now be deployed on the Mina **Devnet**. - -::: - # Smart Contracts You write smart contracts by extending the base class `SmartContract`: @@ -32,7 +26,7 @@ You write smart contracts by extending the base class `SmartContract`: class HelloWorld extends SmartContract {} ``` -The `constructor` of a `SmartContract` is inherited from the base class and cannot be overriden. +The `constructor` of a `SmartContract` is inherited from the base class and cannot be overriden. The zkApp account address (a public key) is its only argument: @@ -48,9 +42,9 @@ let zkApp = new HelloWorld(zkAppAddress); On Mina, there is no strong distinction between normal "user accounts" and "zkApp accounts". A zkApp account: -- Is an account on the Mina blockchain where a zkApp smart contract is deployed. +- Is an account on the Mina blockchain where a zkApp smart contract is deployed. -- Has a verification key associated with it. +- Has a verification key associated with it. The verification key stored on the zkApp account can verify zero knowledge proofs generated with the smart contract. The verification key lives on-chain for a given zkApp account and is used by the Mina network to verify that a zero knowledge proof has met all constraints defined in the prover. See [Prover Function and Verification Key](/zkapps/writing-a-zkapp/introduction-to-zkapps/how-zkapps-work#prover-function-and-verification-key). @@ -83,15 +77,15 @@ The method has one input parameter, `x` of type `Field`. In general, arguments c Internally, every `@method` defines a zk-SNARK circuit. From the cryptography standpoint, a smart contract is a collection of circuits, all of which are compiled into a single prover and a verification key. The proof says something to the effect of "I ran one of these methods, with some private input, and it produced this particular set of account updates". In zero knowledge proof terms, the account updates are the _public input_. The proof is accepted on the network only if it verifies against the verification key stored in the account. This verification requirement ensures that the same zkApp code also ran on the end user's device and that the account updates conform to the smart contract's rules. -### @method +### @method -Inside a `@method`, things sometimes behave a little differently. +Inside a `@method`, things sometimes behave a little differently. To construct a circuit which can then be proven, o1js calls into SnarkyML, a language that builds circuits and connects variables and constraints. As a zkApp developer, you must use the methods, functions, and types provided by o1js. Plain JavaScript code does not call into SnarkyML and therefore is not able to construct circuits. When `SmartContract` is compiled into prover and verification keys, methods are in an environment where the method inputs don't have any concrete values attached to them. Instead, they are like mathematical variables `x`, `y`, `z` that are used to build up abstract computations like `x^2 + y^2` by running the method code. -In contrast, all the variables _have_ actual values attached to them (cryptographers call them "witnesses") during proof generation. +In contrast, all the variables _have_ actual values attached to them (cryptographers call them "witnesses") during proof generation. To log these values for debugging, use a special function for logging from inside your method: ```ts @@ -175,14 +169,14 @@ This code adds the precondition that `this.x` – the on-chain state at verifica Using `this..requireEquals` is more flexible than equating with the current value. For example, `this.x.requireEquals(10)` fixes the on-chain `x` to the number `10`. Why not use `this.x.get()` to add the precondition automatically, instead of writing `this.x.requireEquals(x)`? -To keep things explicit. The assertion reminds you to add logic which makes the proof fail: If `x` isn't the same at verification time, the transaction will be rejected. +To keep things explicit. The assertion reminds you to add logic which makes the proof fail: If `x` isn't the same at verification time, the transaction will be rejected. -So, you must use care to read on-chain values if many users are expected to read and update state concurrently. It is applicable in some situations, but might cause race conditions or call for workarounds, in some situations. +So, you must use care to read on-chain values if many users are expected to read and update state concurrently. It is applicable in some situations, but might cause race conditions or call for workarounds, in some situations. One workaround is to use actions. See [Actions and Reducer](/zkapps/writing-a-zkapp/feature-overview/actions-and-reducer). ## Assertions -Assertions can be incredibly useful to constrain state updates. +Assertions can be incredibly useful to constrain state updates. Common assertions you can use are: @@ -272,7 +266,7 @@ To initialize on-chain state, use the `init()` method. Like the constructor, `init()` is predefined on the base `SmartContract` class. -- It is called when you deploy your zkApp with the zkApp CLI for the first time. +- It is called when you deploy your zkApp with the zkApp CLI for the first time. - It is not called if you upgrade your contract and deploy a second time. You can override this method to add initialization of your on-chain state: @@ -344,7 +338,7 @@ You can create a custom data type for your smart contract using the `Struct` fun 1. Create a class that extends `Struct({ })`. 1. Then, inside the object `{ }`, define the fields that you want to use in your custom data type. -For example, you can create a custom data type called `Point` to represent a 2D point on a grid. The `Point` struct has no instance methods and is used only to hold information about the `x` and `y` points. +For example, you can create a custom data type called `Point` to represent a 2D point on a grid. The `Point` struct has no instance methods and is used only to hold information about the `x` and `y` points. To create the `Point` class, extend the `Struct` class: @@ -379,6 +373,6 @@ export class Grid extends SmartContract { } ``` -Note that your `Struct` classes can contain o1js built-in types like `Field`, `Bool`, `UInt64`, and so on, or even other custom types that you've defined that are based on the `Struct` class. +Note that your `Struct` classes can contain o1js built-in types like `Field`, `Bool`, `UInt64`, and so on, or even other custom types that you've defined that are based on the `Struct` class. This flexibility allows for great composability and reusability of structs. diff --git a/docs/zkapps/writing-a-zkapp/introduction-to-zkapps/testing-zkapps-lightnet.mdx b/docs/zkapps/writing-a-zkapp/introduction-to-zkapps/testing-zkapps-lightnet.mdx index 02ca56d3c..f8c96d90a 100644 --- a/docs/zkapps/writing-a-zkapp/introduction-to-zkapps/testing-zkapps-lightnet.mdx +++ b/docs/zkapps/writing-a-zkapp/introduction-to-zkapps/testing-zkapps-lightnet.mdx @@ -1,7 +1,7 @@ --- title: Testing zkApps with Lightnet hide_title: true -description: Use lightweight Mina blockchain network (Lightnet) for testing on a local blockchain before you test with a live network. +description: Use lightweight Mina blockchain network (Lightnet) for testing on a local blockchain before you test with a live network. keywords: - zkApp CLI - lightnet @@ -10,12 +10,6 @@ keywords: - using zk lightnet --- -:::info - -zkApp programmability is not yet available on the Mina **Mainnet**, but zkApps can now be deployed on the Mina **Devnet**. - -::: - :::caution Use of the **Lightnet** is appropriate for the **local development and testing** only. It is **not** intended to replicate all aspects of the real public networks. @@ -25,18 +19,18 @@ Use of the **Lightnet** is appropriate for the **local development and testing** # Testing zkApps with Lightnet ## What is Lightnet? -It is a fast, resource-efficient solution to launch a lightweight Mina network and associated tools in a single Docker container. +It is a fast, resource-efficient solution to launch a lightweight Mina network and associated tools in a single Docker container. It lets you test zkApps locally on an accurate representation of Mina blockchain before you test same zkApps against the public testnet. Lightnet provides the following benefits: - Reduces the time from ideation to launch by letting you test zkApps against the close-to-real Mina network locally. - Provides the resource-efficient blockchain network with fast startup and syncing times. -- Supports `multi-mode` networks. +- Supports `multi-mode` networks. (single-node network managed by multi-purpose Mina Daemon or multi-node network with diverse participant types) -- Creates and funds accounts so that you can deploy and interact with your zkApps. +- Creates and funds accounts so that you can deploy and interact with your zkApps. The genesis ledger is configured with `1000` pre-funded accounts with the `1550 MINA` balance on each. -- Runs the archive data tools like [Mina archive process](/node-operators/archive-node), `PostgreSQL RDBMS`, [Archive-Node-API](/zkapps/writing-a-zkapp/feature-overview/fetch-events-and-actions) +- Runs the archive data tools like [Mina archive process](/node-operators/archive-node), `PostgreSQL RDBMS`, [Archive-Node-API](/zkapps/writing-a-zkapp/feature-overview/fetch-events-and-actions) (can be disabled if there is no need) - Provides the Mina accounts manager helper tool so you can automate accounts retrieval using, for example, the `Lightnet` [o1js API namespace](https://github.com/o1-labs/o1js/blob/23cdfa3e17a8e8132b70895d34aab711cebd676f/src/lib/mina/fetch.ts#L804). - Simplifies zkApps and network state monitoring by @@ -49,17 +43,17 @@ The genesis ledger is configured with `1000` pre-funded accounts with the `1550 Lightnet requires minimum hardware resources to operate properly. -- Default `single-node` mode +- Default `single-node` mode - `4.5 GB` of RAM to start up - `1.5-2 GB` of RAM to operate - Fewer resources are required if you start the Lightnet without the archive data tools. + Fewer resources are required if you start the Lightnet without the archive data tools. See [start the network without the archive data tools](#start-the-network-without-the-archive-data-tools). - Closer-to-real `multi-node` mode - - More than `16 GB` of RAM + - More than `16 GB` of RAM See [start the multi node network](#start-the-multi-node-network). @@ -80,7 +74,7 @@ The best way to experience Lightnet is by using it via the [`zkapp CLI`](/zkapps ## Start the Lightnet -Most of your zkApp testing can be done on a single node network. +Most of your zkApp testing can be done on a single node network. `Docker Engine` must be running before you can start the Lightnet. ### Start the single node network @@ -114,10 +108,10 @@ $ zk lightnet start --help Some of the `zk lightnet` sub-commands have `boolean` values that default to `true`. -For these sub-commands, the option is active when present. +For these sub-commands, the option is active when present. For example, the default value for `--sync` is `true`, so using `zk lightnet start` is the same as `zk lightnet start --sync`. -For sub-commands that show the option as (`[boolean] [default: true]`), negation happens by adding the `--no-` prefix to the option. +For sub-commands that show the option as (`[boolean] [default: true]`), negation happens by adding the `--no-` prefix to the option. For example, to start Lightnet without waiting for the network to reach the `synchronized` state, use: @@ -133,13 +127,13 @@ To see the options to start the blockchain network with other-than-default setti $ zk lightnet start --help ``` -You can configure different network properties as appropriate to your testing requirements. +You can configure different network properties as appropriate to your testing requirements. ### Start the network without the archive data tools By default, the Lightnet blockchian network starting up also launches the archive data tools such as the `Mina archive process`, the `PostgreSQL RDBMS` and the `Archive-Node-API` application. -To use fewer resources when your testing does not require the archive data tools, you can start the network without them. +To use fewer resources when your testing does not require the archive data tools, you can start the network without them. To disable the archive data tools use the `--no-archive` option: @@ -149,8 +143,8 @@ $ zk lightnet start --no-archive ### Keep the current product versions -New `Docker` images are built and published to the [`Docker Hub`](https://hub.docker.com/r/o1labs/mina-local-network) repository every night. -You might not always want to get the latest product versions. For example, when your zkApp relies on the well-defined APIs and you want to continue developing in your current environment. +New `Docker` images are built and published to the [`Docker Hub`](https://hub.docker.com/r/o1labs/mina-local-network) repository every night. +You might not always want to get the latest product versions. For example, when your zkApp relies on the well-defined APIs and you want to continue developing in your current environment. To keep your current working versions of tools provided by the Lightnet, use the `--no-pull` option: @@ -160,7 +154,7 @@ $ zk lightnet start --no-pull ### Start the multi node network -You can start the network with multiple participants. +You can start the network with multiple participants. Please keep in mind that such the network uses more resources. To start the network in `multi-node` mode with `closer-to-real-world` properties use the following command: @@ -196,8 +190,8 @@ $ zk lightnet stop --no-save-logs ## Configure your zkApp -When you first build your zkApp, you test it locally and create the deploy alias as described in [Tutorial 3: Deploy to a Live Network](/zkapps/tutorials/deploying-to-a-network#deploy-alias) to later use it duting zkApp deployment to the public network. -With Lightnet the deploy alias is automatically configured to be compatible with the lightweight Mina blockchain network. +When you first build your zkApp, you test it locally and create the deploy alias as described in [Tutorial 3: Deploy to a Live Network](/zkapps/tutorials/deploying-to-a-network#deploy-alias) to later use it duting zkApp deployment to the public network. +With Lightnet the deploy alias is automatically configured to be compatible with the lightweight Mina blockchain network. Now that you have Lightnet running, you can execute a single command to configure your zkApp deploy alias in non-interactive mode: @@ -219,7 +213,7 @@ To visualize the network state, launch the lightweight Mina explorer with the fo $ zk lightnet explorer ``` -By default, this command downloads (if needed) and launches the latest version of [lightweight Mina explorer](https://github.com/o1-labs/mina-lightweight-explorer) web application. +By default, this command downloads (if needed) and launches the latest version of [lightweight Mina explorer](https://github.com/o1-labs/mina-lightweight-explorer) web application. To list versions, their published dates, and show the version in use: @@ -252,7 +246,7 @@ You can stream the Docker container processes logs in real time for debugging an $ zk lightnet logs follow ``` -Then select the Docker container process to follow logs for. +Then select the Docker container process to follow logs for. Press `Ctrl+C` to stop streaming. @@ -270,7 +264,7 @@ The network status is returned, including HTTP endpoints, network propertis and Each Docker image is packaged with the `genesis ledger` that is configured with `1000` pre-funded accounts with the `1550 MINA` balance on each. -The Mina [`accounts manager`](https://github.com/shimkiv/mina-accounts-manager) helper tool provides the random key pair from the genesis ledger. +The Mina [`accounts manager`](https://github.com/shimkiv/mina-accounts-manager) helper tool provides the random key pair from the genesis ledger. By default it is available at the [http://localhost:8181/](http://localhost:8181/). This endpoint is the same for all users and is available when the Lightnet is up and running. Use HTTP endpoints to manage accounts: @@ -278,10 +272,10 @@ Use HTTP endpoints to manage accounts: ```text HTTP GET: http://localhost:8181/acquire-account - Supported Query params: + Supported Query params: isRegularAccount=, default: true Useful if you need to get non-zkApp account. - + unlockAccount=, default: false Useful if you need to get unlocked account. Returns JSON account key-pair: @@ -319,12 +313,12 @@ Use HTTP endpoints to manage accounts: ### Lightnet o1js API namespace -The `acquireKeyPair()`, `releaseKeyPair()`, and `listAcquiredKeyPairs()` methods in the `Lightnet` o1js API namespace handle the communication with the running Mina accounts manager helper tool. +The `acquireKeyPair()`, `releaseKeyPair()`, and `listAcquiredKeyPairs()` methods in the `Lightnet` o1js API namespace handle the communication with the running Mina accounts manager helper tool. For details, see the source code comments of the correspointing [namespace](https://github.com/o1-labs/o1js/blob/23cdfa3e17a8e8132b70895d34aab711cebd676f/src/lib/mina/fetch.ts#L804) methods. For the real-world example of using Lightnet and o1js API, see [run-live.ts](https://github.com/o1-labs/o1js/blob/main/src/examples/zkapps/hello-world/run-live.ts) example file. ## Feedback and contributions -Share your feedback, submit feature requests, and report issues with Lightnet at the [zkapp-cli GitHub repository](https://github.com/o1-labs/zkapp-cli). +Share your feedback, submit feature requests, and report issues with Lightnet at the [zkapp-cli GitHub repository](https://github.com/o1-labs/zkapp-cli). Remember to use the `lightnet` label. diff --git a/docs/zkapps/writing-a-zkapp/introduction-to-zkapps/testing-zkapps-locally.mdx b/docs/zkapps/writing-a-zkapp/introduction-to-zkapps/testing-zkapps-locally.mdx index c79190d91..e1c22f3c0 100644 --- a/docs/zkapps/writing-a-zkapp/introduction-to-zkapps/testing-zkapps-locally.mdx +++ b/docs/zkapps/writing-a-zkapp/introduction-to-zkapps/testing-zkapps-locally.mdx @@ -11,12 +11,6 @@ keywords: - Docker test --- -:::info - -zkApp programmability is not yet available on the Mina **Mainnet**, but zkApps can now be deployed on the Mina **Devnet**. - -::: - # Testing zkApps Locally Before you can test your zkApps, create automated tests for your smart contract and test with a simulated local blockchain. Test automation is essential to ensure your code is well-tested during development. @@ -55,7 +49,7 @@ For basic test examples that deploy and update the state on a smart contract usi To run all test files in your project, run these commands from your project's root directory: -- `npm run test` +- `npm run test` - `npm run testw` for watchmode To generate a test coverage report for your project, run: From 3e63b4fe571757b0751066dd3c80fb755cf6423b Mon Sep 17 00:00:00 2001 From: Serhii Shymkiv Date: Mon, 3 Jun 2024 19:18:35 +0300 Subject: [PATCH 03/12] Remove libp2p keypair generation from the Node operator requirements. --- docs/node-operators/requirements.mdx | 9 --------- 1 file changed, 9 deletions(-) diff --git a/docs/node-operators/requirements.mdx b/docs/node-operators/requirements.mdx index a783a739f..5a399821a 100644 --- a/docs/node-operators/requirements.mdx +++ b/docs/node-operators/requirements.mdx @@ -39,15 +39,6 @@ Mina uses by default the port `8302` which is the default libp2p port. You can use a different port by setting the `--external-port` flag. -### Generation of libp2p keypair​ - -Each node within the network must possess its own distinct libp2p key pair. Although the same libp2p keys can be reused from before the upgrade, if you need to manually generate new libp2p keys, use the following command: - -``` -mina libp2p generate-keypair -privkey-path -``` -Further information on [generating key pairs](/node-operators/generating-a-keypair) on Mina Protocol. - ### Node Auto-restart Ensure your nodes are set to restart automatically after a crash. For guidance, refer to the [auto-restart instructions](/node-operators/block-producer-node/connecting-to-the-network#start-a-mina-node-with-auto-restart-flows-using-systemd) From 9da5363977207f6b825384b1ba3eea5ea78cde0d Mon Sep 17 00:00:00 2001 From: Serhii Shymkiv Date: Mon, 3 Jun 2024 21:54:09 +0300 Subject: [PATCH 04/12] Update side menu sections to be links. --- sidebars.js | 140 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 140 insertions(+) diff --git a/sidebars.js b/sidebars.js index d251fcbeb..dddcc0673 100644 --- a/sidebars.js +++ b/sidebars.js @@ -4,6 +4,10 @@ module.exports = { { type: 'category', label: 'About Mina', + link: { + type: 'doc', + id: 'about-mina/index', + }, items: [ 'about-mina/index', 'about-mina/what-are-zero-knowledge-proofs', @@ -21,6 +25,10 @@ module.exports = { { type: 'category', label: 'Using Mina', + link: { + type: 'doc', + id: 'using-mina/install-a-wallet', + }, items: [ 'using-mina/install-a-wallet', 'using-mina/ledger-hardware-wallet', @@ -32,10 +40,18 @@ module.exports = { { type: 'category', label: 'zkApp Developers', + link: { + type: 'doc', + id: 'zkapps/o1js/index', + }, items: [ { type: 'category', label: 'o1js', + link: { + type: 'doc', + id: 'zkapps/o1js/index', + }, items: [ 'zkapps/o1js/index', 'zkapps/o1js/basic-concepts', @@ -52,11 +68,19 @@ module.exports = { { type: 'category', label: 'zkApps', + link: { + type: 'doc', + id: 'zkapps/writing-a-zkapp/index', + }, items: [ 'zkapps/writing-a-zkapp/index', { type: 'category', label: 'Introduction to zkApps', + link: { + type: 'doc', + id: 'zkapps/writing-a-zkapp/introduction-to-zkapps/how-zkapps-work', + }, items: [ 'zkapps/writing-a-zkapp/introduction-to-zkapps/how-zkapps-work', 'zkapps/writing-a-zkapp/introduction-to-zkapps/install-zkapp-cli', @@ -74,6 +98,10 @@ module.exports = { { type: 'category', label: 'Feature Overview', + link: { + type: 'doc', + id: 'zkapps/writing-a-zkapp/feature-overview/on-chain-values', + }, items: [ 'zkapps/writing-a-zkapp/feature-overview/on-chain-values', 'zkapps/writing-a-zkapp/feature-overview/offchain-storage', @@ -90,6 +118,10 @@ module.exports = { { type: 'category', label: 'Advanced', + link: { + type: 'doc', + id: 'zkapps/advanced/experimental', + }, items: [ 'zkapps/advanced/experimental', 'zkapps/advanced/zkapps-for-ethereum-developers', @@ -98,6 +130,10 @@ module.exports = { { type: 'category', label: 'Tutorials', + link: { + type: 'doc', + id: 'zkapps/tutorials/index', + }, items: [ 'zkapps/tutorials/index', 'zkapps/tutorials/hello-world', @@ -116,6 +152,10 @@ module.exports = { { type: 'category', label: 'o1js Reference', + link: { + type: 'doc', + id: 'zkapps/o1js-reference/README', + }, items: [ { type: 'doc', @@ -125,6 +165,10 @@ module.exports = { { type: 'category', label: 'Classes', + link: { + type: 'doc', + id: 'zkapps/o1js-reference/classes/AccountUpdate', + }, items: [ { type: 'doc', @@ -351,6 +395,10 @@ module.exports = { { type: 'category', label: 'Functions', + link: { + type: 'doc', + id: 'zkapps/o1js-reference/functions/Bytes', + }, items: [ { type: 'doc', @@ -582,6 +630,10 @@ module.exports = { { type: 'category', label: 'Interfaces', + link: { + type: 'doc', + id: 'zkapps/o1js-reference/interfaces/Permissions', + }, items: [ { type: 'doc', @@ -593,10 +645,18 @@ module.exports = { { type: 'category', label: 'Namespaces', + link: { + type: 'doc', + id: 'zkapps/o1js-reference/namespaces/Crypto/README', + }, items: [ { type: 'category', label: 'Crypto', + link: { + type: 'doc', + id: 'zkapps/o1js-reference/namespaces/Crypto/README', + }, items: [ { type: 'doc', @@ -606,6 +666,10 @@ module.exports = { { type: 'category', label: 'Type-Aliases', + link: { + type: 'doc', + id: 'zkapps/o1js-reference/namespaces/Crypto/type-aliases/Curve', + }, items: [ { type: 'doc', @@ -624,6 +688,10 @@ module.exports = { { type: 'category', label: 'Encryption', + link: { + type: 'doc', + id: 'zkapps/o1js-reference/namespaces/Encryption/README', + }, items: [ { type: 'doc', @@ -633,6 +701,10 @@ module.exports = { { type: 'category', label: 'Functions', + link: { + type: 'doc', + id: 'zkapps/o1js-reference/namespaces/Encryption/functions/decrypt', + }, items: [ { type: 'doc', @@ -651,6 +723,10 @@ module.exports = { { type: 'category', label: 'Experimental', + link: { + type: 'doc', + id: 'zkapps/o1js-reference/namespaces/Experimental/README', + }, items: [ { type: 'doc', @@ -660,6 +736,10 @@ module.exports = { { type: 'category', label: 'Classes', + link: { + type: 'doc', + id: 'zkapps/o1js-reference/namespaces/Experimental/classes/OffchainStateCommitments', + }, items: [ { type: 'doc', @@ -671,6 +751,10 @@ module.exports = { { type: 'category', label: 'Functions', + link: { + type: 'doc', + id: 'zkapps/o1js-reference/namespaces/Experimental/functions/OffchainState', + }, items: [ { type: 'doc', @@ -689,6 +773,10 @@ module.exports = { { type: 'category', label: 'Lightnet', + link: { + type: 'doc', + id: 'zkapps/o1js-reference/namespaces/Lightnet/README', + }, items: [ { type: 'doc', @@ -698,6 +786,10 @@ module.exports = { { type: 'category', label: 'Functions', + link: { + type: 'doc', + id: 'zkapps/o1js-reference/namespaces/Lightnet/functions/acquireKeyPair', + }, items: [ { type: 'doc', @@ -721,6 +813,10 @@ module.exports = { { type: 'category', label: 'Mina', + link: { + type: 'doc', + id: 'zkapps/o1js-reference/namespaces/Mina/README', + }, items: [ { type: 'doc', @@ -730,6 +826,10 @@ module.exports = { { type: 'category', label: 'Functions', + link: { + type: 'doc', + id: 'zkapps/o1js-reference/namespaces/Mina/functions/LocalBlockchain', + }, items: [ { type: 'doc', @@ -841,10 +941,18 @@ module.exports = { { type: 'category', label: 'Namespaces', + link: { + type: 'doc', + id: 'zkapps/o1js-reference/namespaces/Mina/namespaces/TestPublicKey/README', + }, items: [ { type: 'category', label: 'TestPublicKey', + link: { + type: 'doc', + id: 'zkapps/o1js-reference/namespaces/Mina/namespaces/TestPublicKey/README', + }, items: [ { type: 'doc', @@ -854,6 +962,10 @@ module.exports = { { type: 'category', label: 'Functions', + link: { + type: 'doc', + id: 'zkapps/o1js-reference/namespaces/Mina/namespaces/TestPublicKey/functions/random', + }, items: [ { type: 'doc', @@ -867,6 +979,10 @@ module.exports = { { type: 'category', label: 'Transaction', + link: { + type: 'doc', + id: 'zkapps/o1js-reference/namespaces/Mina/namespaces/Transaction/README', + }, items: [ { type: 'doc', @@ -876,6 +992,10 @@ module.exports = { { type: 'category', label: 'Functions', + link: { + type: 'doc', + id: 'zkapps/o1js-reference/namespaces/Mina/namespaces/Transaction/functions/fromJSON', + }, items: [ { type: 'doc', @@ -891,6 +1011,10 @@ module.exports = { { type: 'category', label: 'Type-Aliases', + link: { + type: 'doc', + id: 'zkapps/o1js-reference/namespaces/Mina/type-aliases/ActionStates', + }, items: [ { type: 'doc', @@ -947,6 +1071,10 @@ module.exports = { { type: 'category', label: 'Variables', + link: { + type: 'doc', + id: 'zkapps/o1js-reference/namespaces/Mina/variables/activeInstance', + }, items: [ { type: 'doc', @@ -962,6 +1090,10 @@ module.exports = { { type: 'category', label: 'Type-Aliases', + link: { + type: 'doc', + id: 'zkapps/o1js-reference/type-aliases/Account', + }, items: [ { type: 'doc', @@ -1143,6 +1275,10 @@ module.exports = { { type: 'category', label: 'Variables', + link: { + type: 'doc', + id: 'zkapps/o1js-reference/variables/Account', + }, items: [ { type: 'doc', @@ -1413,6 +1549,10 @@ module.exports = { { type: 'category', label: 'Participate', + link: { + type: 'doc', + id: 'participate/online-communities', + }, items: [ 'participate/online-communities', 'participate/office-hours', From ac6546b7106cf081af65542973d401dcf6d36a17 Mon Sep 17 00:00:00 2001 From: Serhii Shymkiv Date: Tue, 4 Jun 2024 10:16:17 +0300 Subject: [PATCH 05/12] Rework libp2p requirements. --- docs/node-operators/generating-a-keypair.mdx | 60 +++++--------------- docs/node-operators/requirements.mdx | 16 +++++- docs/node-operators/seed-peers/index.mdx | 2 +- 3 files changed, 29 insertions(+), 49 deletions(-) diff --git a/docs/node-operators/generating-a-keypair.mdx b/docs/node-operators/generating-a-keypair.mdx index 5ca9f90b3..d3bf69f1c 100644 --- a/docs/node-operators/generating-a-keypair.mdx +++ b/docs/node-operators/generating-a-keypair.mdx @@ -30,7 +30,7 @@ In some cases, you want to generate more than one wallet key pair. For example, The supported tools for generating public/private key pairs are: - [mina-generate-keypair](#mina-generate-keypair) command line utility -- [mina libp2p generate-keypair](#mina-libp2p-generate-keypair) mina subcommand +- [mina libp2p generate-keypair](#generating-and-using-your-libp2p-keys) mina subcommand - [Mina Signer](/node-operators/mina-signer) - [Mina command line wallet package](https://github.com/jspada/ledger-app-mina/blob/v1.0.0-beta.2/README.md#command-line-wallet) that interfaces with your Ledger device and Mina blockchain to generate addresses on the Ledger hardware wallet @@ -167,58 +167,20 @@ docker run -it --rm --entrypoint "" \ mina advanced validate-keypair --privkey-path /keys/my-wallet ``` -## mina libp2p generate-keypair - -Each node in the Mina network must possess its own distinct libp2p key pair. This requirement extends to block producer nodes, despite their utilization of a common block production key. Every node operator must generate unique libp2p keys locally on their respective machines. - -Use the `mina` subcommand `libp2p` command line utility to create a libp2p key pair. +## Generating and using your libp2p keys +To ensure connectivity across the network, it is essential that all seed nodes start with the **same** `libp2p` keypair. +This consistency allows other nodes in the network to reliably connect. +Use the `libp2p` subcommand of `mina` CLI utility to create a libp2p key pair. ``` -Mina - - mina SUBCOMMAND - -=== subcommands === - - accounts Client commands concerning account management - daemon Mina daemon - client Lightweight client commands - advanced Advanced client commands - ledger Ledger commands - libp2p Libp2p commands - internal Internal commands - parallel-worker internal use only - transaction-snark-profiler transaction snark profiler - version print version information - help explain a given subcommand (perhaps recursively) - ``` - - The `libp2p` subcommand is used to create the libp2p key pair. - - ``` - Generate a new libp2p keypair and print out the peer ID - - mina libp2p generate-keypair - -=== flags === - - --privkey-path FILE File to write private key into (public key will be - FILE.pub) - (alias: -privkey-path) - [-help] print this help text and exit - (alias: -?) - ``` -### Installation Instructions - -See [Getting Started](./block-producer-node/getting-started) - -## Generate your libp2p keys +mina libp2p generate-keypair --privkey-path +``` -Use the following command: +Generated libp2p keys can then be used with the Mina Daemon startup command like this: ``` -mina libp2p generate-keypair -privkey-path +mina daemon ... --libp2p-keypair ... ``` ## Ledger Hardware Wallet @@ -229,6 +191,10 @@ You can use your [Ledger Nano S](https://www.ledger.com/) hardware wallet to sec You can also use [Mina Signer](/node-operators/mina-signer) to generate key pairs and sign transactions. +## Installation Instructions + +See [Getting Started](./block-producer-node/getting-started) + ## Next steps Now that you have created a public/private key pair, you are ready to [connect to the network](./block-producer-node/connecting-to-the-network) or share your public key. diff --git a/docs/node-operators/requirements.mdx b/docs/node-operators/requirements.mdx index 5a399821a..61ed77dc4 100644 --- a/docs/node-operators/requirements.mdx +++ b/docs/node-operators/requirements.mdx @@ -26,7 +26,7 @@ Please note the following are the hardware requirements for each node type after ## Mina Daemon Requirements -### IP and Port configuration​ +### IP and Port configuration **IP:** @@ -42,3 +42,17 @@ You can use a different port by setting the `--external-port` flag. ### Node Auto-restart Ensure your nodes are set to restart automatically after a crash. For guidance, refer to the [auto-restart instructions](/node-operators/block-producer-node/connecting-to-the-network#start-a-mina-node-with-auto-restart-flows-using-systemd) + +## Seed Peer Requirements + +### Generation of libp2p keypair + +To ensure connectivity across the network, it is essential that all seed nodes start with the **same** `libp2p` keypair. +This consistency allows other nodes in the network to reliably connect. +Although the same libp2p keys can be reused from before the upgrade, if you need to manually generate new libp2p keys, use the following command: + +``` +mina libp2p generate-keypair --privkey-path +``` + +Further information on [generating key pairs](/node-operators/generating-a-keypair) on Mina Protocol. diff --git a/docs/node-operators/seed-peers/index.mdx b/docs/node-operators/seed-peers/index.mdx index 074b9d26d..497904a91 100644 --- a/docs/node-operators/seed-peers/index.mdx +++ b/docs/node-operators/seed-peers/index.mdx @@ -11,7 +11,7 @@ keywords: Seed peer providers are an independent group of nodes that assist new nodes to find peers and connect to the Mina Protocol. Seed peers improve the onboarding experience for other nodes and make sure the nodes start bootstrapping as soon as possible. -Mina’s seed peers are considered to be leaders among the community. They are not compensated in any way – they perform their role as a service to the Mina community. +Mina's seed peers are considered to be leaders among the community. They are not compensated in any way - they perform their role as a service to the Mina community. For the full list of seed peers and information on how to contribute, please refer to the [Official Git Repository](https://github.com/MinaFoundation/seeds). From c1ff3f689dff7f614aefa4fa067933b41c692833 Mon Sep 17 00:00:00 2001 From: Serhii Shymkiv Date: Tue, 4 Jun 2024 10:37:23 +0300 Subject: [PATCH 06/12] Sidebar leftovers. --- sidebars.js | 24 ++++-------------------- 1 file changed, 4 insertions(+), 20 deletions(-) diff --git a/sidebars.js b/sidebars.js index 8e42b9f43..b4070e750 100644 --- a/sidebars.js +++ b/sidebars.js @@ -2,25 +2,9 @@ module.exports = { docs: [ 'welcome', { - type: 'category', + type: 'link', label: 'About Mina', - link: { - type: 'doc', - id: 'about-mina/index', - }, - items: [ - 'about-mina/index', - 'about-mina/what-are-zero-knowledge-proofs', - 'about-mina/protocol-architecture', - 'about-mina/consensus', - 'about-mina/security', - 'about-mina/faq', - { - type: 'link', - label: 'Whitepaper', - href: 'https://minaprotocol.com/wp-content/uploads/economicsWhitepaper.pdf', - }, - ], + href: 'https://minaprotocol.com/about', }, { type: 'category', @@ -1557,12 +1541,12 @@ module.exports = { { type: 'link', label: 'Online Communities', - href: 'https://minaprotocol.com/community' + href: 'https://minaprotocol.com/community', }, { type: 'link', label: 'Apply for Grants', - href: 'https://minaprotocol.com/blog/mina-developers-grants' + href: 'https://minaprotocol.com/blog/mina-developers-grants', }, 'participate/office-hours', 'participate/careers', From c1ec3f2ad61f42a459b8f02297ec44a9de63fdf3 Mon Sep 17 00:00:00 2001 From: Serhii Shymkiv Date: Tue, 4 Jun 2024 10:40:22 +0300 Subject: [PATCH 07/12] Sidebar leftovers. --- sidebars.js | 4 ---- 1 file changed, 4 deletions(-) diff --git a/sidebars.js b/sidebars.js index b4070e750..209529374 100644 --- a/sidebars.js +++ b/sidebars.js @@ -1533,10 +1533,6 @@ module.exports = { { type: 'category', label: 'Participate', - link: { - type: 'doc', - id: 'participate/online-communities', - }, items: [ { type: 'link', From 5e83754085b673e32f9f2ec1f190570de6ce38bb Mon Sep 17 00:00:00 2001 From: Serhii Shymkiv Date: Tue, 4 Jun 2024 11:05:36 +0300 Subject: [PATCH 08/12] Fix for broken links. --- src/components/features/HomepageFeatures.tsx | 23 +++++++++++--------- 1 file changed, 13 insertions(+), 10 deletions(-) diff --git a/src/components/features/HomepageFeatures.tsx b/src/components/features/HomepageFeatures.tsx index 409af0062..5458ae9b3 100644 --- a/src/components/features/HomepageFeatures.tsx +++ b/src/components/features/HomepageFeatures.tsx @@ -7,10 +7,10 @@ import React from 'react'; import styles from './HomepageFeatures.module.scss'; +import Link from '@docusaurus/Link'; import Button from '@site/src/components/common/Button'; import Subhead from '@site/src/components/common/Subhead'; import ArrowRightSmall from '@site/static/svg/common/arrow_right_small.svg'; -import Link from '@docusaurus/Link'; type FeatureItem = { title: string; @@ -49,18 +49,15 @@ const FeatureList: FeatureItem[] = [ title: 'About Mina', image: '/svg/homepage/about_mina.svg', buttonText: 'About Mina', - buttonLink: '/about-mina', + buttonLink: 'https://minaprotocol.com/about', description: ( <> {'Learn '} - + about Mina , - + {' '} zero knowledge proofs{' '} @@ -108,14 +105,20 @@ const FeatureList: FeatureItem[] = [ title: 'Participate', image: '/svg/homepage/participate.svg', buttonText: 'Online Communities', - buttonLink: '/participate/online-communities', + buttonLink: 'https://minaprotocol.com/community', description: ( <> - + Join the community ,{' '} - + apply for grants & the zkApps Builders Program ,{' '} From 8456616362d875854ad2e2e69d5c784d328b6edc Mon Sep 17 00:00:00 2001 From: Serhii Shymkiv Date: Tue, 4 Jun 2024 11:51:48 +0300 Subject: [PATCH 09/12] Zk link. --- src/components/features/HomepageFeatures.tsx | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/src/components/features/HomepageFeatures.tsx b/src/components/features/HomepageFeatures.tsx index 5458ae9b3..0e7e4408e 100644 --- a/src/components/features/HomepageFeatures.tsx +++ b/src/components/features/HomepageFeatures.tsx @@ -57,7 +57,10 @@ const FeatureList: FeatureItem[] = [ about Mina , - + {' '} zero knowledge proofs{' '} From a2e2e2955f02b4266227d5800c92723dfba65c41 Mon Sep 17 00:00:00 2001 From: Serhii Shymkiv Date: Tue, 4 Jun 2024 12:07:56 +0300 Subject: [PATCH 10/12] Welcome page mainnet release caution. --- docs/welcome.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/welcome.mdx b/docs/welcome.mdx index 4be98db3d..48d282e4b 100644 --- a/docs/welcome.mdx +++ b/docs/welcome.mdx @@ -9,7 +9,7 @@ import HomepageFeatures from "@site/src/components/features/HomepageFeatures"; # Welcome -:::caution Berkeley Release has landed +:::caution Berkeley Mainnet release has landed Please make sure to upgrade your mina nodes to **3.0.0** ([Release notes](https://github.com/MinaProtocol/mina/discussions/15662) **<_CHANGE_ME_>**) From f77cfd948c89095c269d82afd85a83eff649475a Mon Sep 17 00:00:00 2001 From: David Lehuby Date: Wed, 5 Jun 2024 03:52:38 +1000 Subject: [PATCH 11/12] Update git sha and chain id --- docs/node-operators/flags-configs.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/node-operators/flags-configs.mdx b/docs/node-operators/flags-configs.mdx index 42ffb3a86..f44985557 100644 --- a/docs/node-operators/flags-configs.mdx +++ b/docs/node-operators/flags-configs.mdx @@ -18,10 +18,10 @@ Please refer to the Berkeley node release notes [here](https://github.com/MinaPr ``` Chain ID -5f704cc0c82e0ed70e873f0893d7e06f148524e3f0bdae2afb02e7819a0c24d1 **<_CHANGE_ME_>** +a7351abc7ddf2ea92d1b38cc8e636c271c1dfd2c081c637f62ebc2af34eb7cc1 Git SHA-1 -039296a260080ed02d0d0750d185921f030b6c9c **<_CHANGE_ME_>** +93e02797f72abe2cbf8dfca6f2328e9c8cd76546 Seed List https://bootnodes.minaprotocol.com/networks/mainnet.txt From 91424156a66ed91e094298194c70162a22f1aafc Mon Sep 17 00:00:00 2001 From: David Lehuby Date: Wed, 5 Jun 2024 04:09:22 +1000 Subject: [PATCH 12/12] Update Mainnet Version to 3.0.0-93e0279 --- docs/exchange-operators/rosetta/run-with-docker.mdx | 2 +- docs/node-developers/sandbox-node.mdx | 2 +- docs/node-operators/archive-node/getting-started.mdx | 12 ++++++------ .../connecting-to-the-network.mdx | 2 +- .../block-producer-node/getting-started.mdx | 4 ++-- docs/node-operators/flags-configs.mdx | 2 +- docs/node-operators/generating-a-keypair.mdx | 12 ++++++------ docs/node-operators/seed-peers/getting-started.mdx | 2 +- docs/welcome.mdx | 2 +- 9 files changed, 20 insertions(+), 20 deletions(-) diff --git a/docs/exchange-operators/rosetta/run-with-docker.mdx b/docs/exchange-operators/rosetta/run-with-docker.mdx index 6ea7213bd..3141267ea 100644 --- a/docs/exchange-operators/rosetta/run-with-docker.mdx +++ b/docs/exchange-operators/rosetta/run-with-docker.mdx @@ -46,7 +46,7 @@ Run the container with following command (replace the image tag with one from do docker run -it --rm --name rosetta \ --entrypoint=./docker-start.sh \ -p 10101:10101 -p 3085:3085 -p 3086:3086 -p 3087:3087 \ - minaprotocol/mina-rosetta:2.0.0-039296a-focal **<_CHANGE_ME_>** + minaprotocol/mina-rosetta:3.0.0-93e0279-focal You can also create a file with the environment variables and pass it to the docker run command with `--env-file` flag. For example, create a file named `mainnet.env` with the following content: diff --git a/docs/node-developers/sandbox-node.mdx b/docs/node-developers/sandbox-node.mdx index 65f3f93ab..98318f0a3 100644 --- a/docs/node-developers/sandbox-node.mdx +++ b/docs/node-developers/sandbox-node.mdx @@ -26,7 +26,7 @@ docker run \ --name mina \ -e RUN_DEMO=true \ -e MINA_PRIVKEY_PASS='' \ - minaprotocol/mina-daemon:2.0.0-039296a-bullseye-mainnet **<_CHANGE_ME_>** + minaprotocol/mina-daemon:3.0.0-93e0279-bullseye-mainnet ``` diff --git a/docs/node-operators/archive-node/getting-started.mdx b/docs/node-operators/archive-node/getting-started.mdx index 7ff28e982..f75e9ca84 100644 --- a/docs/node-operators/archive-node/getting-started.mdx +++ b/docs/node-operators/archive-node/getting-started.mdx @@ -55,13 +55,13 @@ Running an archive node requires some knowledge of managing a PostgreSQL databas - Ubuntu/Debian: ``` - sudo apt-get install mina-archive=2.0.0-039296a **<_CHANGE_ME_>** + sudo apt-get install mina-archive=3.0.0-93e0279 ``` - Docker: ``` - minaprotocol/mina-archive:2.0.0-039296a-bullseye **<_CHANGE_ME_>** + minaprotocol/mina-archive:3.0.0-93e0279-bullseye ``` ## Set up the archive node @@ -125,7 +125,7 @@ To get started with installing and running the archive node using Docker, follow 2. Pull the archive node image from Docker Hub. ```sh - docker pull minaprotocol/mina-archive:2.0.0-039296a-bullseye **<_CHANGE_ME_>** + docker pull minaprotocol/mina-archive:3.0.0-93e0279-bullseye ``` 3. Pull and install the postgres image from Docker Hub. @@ -168,7 +168,7 @@ To get started with installing and running the archive node using Docker, follow --name archive \ -p 3086:3086 \ -v /tmp/archive:/data \ - minaprotocol/mina-archive:2.0.0-039296a-bullseye \ **<_CHANGE_ME_>** + minaprotocol/mina-archive:3.0.0-93e0279-bullseye \ mina-archive run \ --postgres-uri postgres://postgres:postgres@postgres:5432/archive \ --server-port 3086 @@ -212,7 +212,7 @@ To run the archive node using Docker Compose: 3. Pull the archive node image from Docker Hub. ```sh - docker pull minaprotocol/mina-archive:2.0.0-039296a-bullseye **<_CHANGE_ME_>** + docker pull minaprotocol/mina-archive:3.0.0-93e0279-bullseye ``` 4. Pull and install the postgres image from Docker Hub. @@ -240,7 +240,7 @@ To run the archive node using Docker Compose: ports: - '5432:5432' archive: - image: 'minaprotocol/mina-archive:2.0.0-039296a-bullseye' **<_CHANGE_ME_>** + image: 'minaprotocol/mina-archive:3.0.0-93e0279-bullseye' command: >- mina-archive run --postgres-uri postgres://postgres:postgres@postgres:5432/archive --server-port 3086 diff --git a/docs/node-operators/block-producer-node/connecting-to-the-network.mdx b/docs/node-operators/block-producer-node/connecting-to-the-network.mdx index 22dc467a3..8b19f0a99 100644 --- a/docs/node-operators/block-producer-node/connecting-to-the-network.mdx +++ b/docs/node-operators/block-producer-node/connecting-to-the-network.mdx @@ -179,7 +179,7 @@ docker run --name mina -d \ --mount "type=bind,source=$(pwd)/.mina-env,dst=/entrypoint.d/mina-env,readonly" \ --mount "type=bind,source=$(pwd)/keys,dst=/keys,readonly" \ --mount "type=bind,source=$(pwd)/.mina-config,dst=/root/.mina-config" \ -minaprotocol/mina-daemon:2.0.0-039296a-bullseye-mainnet \ **<_CHANGE_ME_>** +minaprotocol/mina-daemon:3.0.0-93e0279-bullseye-mainnet \ daemon ``` diff --git a/docs/node-operators/block-producer-node/getting-started.mdx b/docs/node-operators/block-producer-node/getting-started.mdx index 3f95ea560..60bbfdf4e 100644 --- a/docs/node-operators/block-producer-node/getting-started.mdx +++ b/docs/node-operators/block-producer-node/getting-started.mdx @@ -79,7 +79,7 @@ sudo apt-get update Now install the node package. ``` -sudo apt-get install -y curl unzip mina-mainnet=2.0.0-039296a **<_CHANGE_ME_>** +sudo apt-get install -y curl unzip mina-mainnet=3.0.0-93e0279 ``` @@ -87,7 +87,7 @@ To verify the mina daemon installation, run: - `mina version` -The expected output is `Commit 039296a260080ed02d0d0750d185921f030b6c9c on branch master`. +The expected output is `Commit 93e02797f72abe2cbf8dfca6f2328e9c8cd76546 on branch berkeley`. ### If you are using Ufw, allow these permissions diff --git a/docs/node-operators/flags-configs.mdx b/docs/node-operators/flags-configs.mdx index f44985557..7f7e63e3d 100644 --- a/docs/node-operators/flags-configs.mdx +++ b/docs/node-operators/flags-configs.mdx @@ -127,7 +127,7 @@ docker run --name rosetta --rm \ -p 3088:3088 \ --entrypoint '' \ -gcr.io/o1labs-192920/mina-rosetta: **<_CHANGE_ME_>** \ +gcr.io/o1labs-192920/mina-rosetta:3.0.0-93e0279 \ /usr/local/bin/mina-rosetta \ --archive-uri "${PG_CONNECTION_STRING}" \ --graphql-uri "${GRAPHQL_URL}" \ diff --git a/docs/node-operators/generating-a-keypair.mdx b/docs/node-operators/generating-a-keypair.mdx index d3bf69f1c..3ae30ccb4 100644 --- a/docs/node-operators/generating-a-keypair.mdx +++ b/docs/node-operators/generating-a-keypair.mdx @@ -74,7 +74,7 @@ Generate a new public, private keypair ```sh echo "deb [trusted=yes] http://packages.o1test.net $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/mina.list sudo apt-get update - sudo apt-get install -y mina-mainnet=2.0.0-039296a **<_CHANGE_ME_>** + sudo apt-get install -y mina-mainnet=3.0.0-93e0279 ``` 1. Verify that the key generation tool installed correctly: @@ -86,7 +86,7 @@ Generate a new public, private keypair The expected output is: ``` - Commit 039296a260080ed02d0d0750d185921f030b6c9c on branch compatible + Commit 93e02797f72abe2cbf8dfca6f2328e9c8cd76546 on branch berkeley ``` ### macOS, Windows, and platforms other than Ubuntu and Debian @@ -129,7 +129,7 @@ Make sure to set a new and secure password for the following commands. Mina will cd ~ docker run -it --rm --entrypoint "" \ --volume $(pwd)/keys:/keys \ - minaprotocol/mina-daemon:2.0.0-039296a-bullseye-mainnet \ **<_CHANGE_ME_>** + minaprotocol/mina-daemon:3.0.0-93e0279-bullseye-mainnet \ mina advanced generate-keypair --privkey-path /keys/my-wallet ``` @@ -163,14 +163,14 @@ On Docker: ``` docker run -it --rm --entrypoint "" \ --volume $(pwd)/keys:/keys \ - minaprotocol/mina-daemon:2.0.0-039296a-bullseye-mainnet \ **<_CHANGE_ME_>** + minaprotocol/mina-daemon:3.0.0-93e0279-bullseye-mainnet \ mina advanced validate-keypair --privkey-path /keys/my-wallet ``` ## Generating and using your libp2p keys -To ensure connectivity across the network, it is essential that all seed nodes start with the **same** `libp2p` keypair. -This consistency allows other nodes in the network to reliably connect. +To ensure connectivity across the network, it is essential that all seed nodes start with the **same** `libp2p` keypair. +This consistency allows other nodes in the network to reliably connect. Use the `libp2p` subcommand of `mina` CLI utility to create a libp2p key pair. ``` diff --git a/docs/node-operators/seed-peers/getting-started.mdx b/docs/node-operators/seed-peers/getting-started.mdx index 46cad9c4f..d0d6ccb9b 100644 --- a/docs/node-operators/seed-peers/getting-started.mdx +++ b/docs/node-operators/seed-peers/getting-started.mdx @@ -88,7 +88,7 @@ docker run --name mina-seed-node -d \ -v "$(pwd)/keys:/root/keys:ro" \ -v "$(pwd)/.mina-config:/root/.mina-config" \ -v "$(pwd)/.mina-env:/entrypoint.d/mina-env:ro" \ -minaprotocol/mina-daemon:2.0.0-039296a-bullseye-mainnet \ **<_CHANGE_ME_>** +minaprotocol/mina-daemon:3.0.0-93e0279-bullseye-mainnet \ daemon ``` diff --git a/docs/welcome.mdx b/docs/welcome.mdx index 48d282e4b..89c3a65ca 100644 --- a/docs/welcome.mdx +++ b/docs/welcome.mdx @@ -11,7 +11,7 @@ import HomepageFeatures from "@site/src/components/features/HomepageFeatures"; :::caution Berkeley Mainnet release has landed -Please make sure to upgrade your mina nodes to **3.0.0** ([Release notes](https://github.com/MinaProtocol/mina/discussions/15662) **<_CHANGE_ME_>**) +Please make sure to upgrade your mina nodes to **3.0.0** ([Release notes](https://github.com/MinaProtocol/mina/releases/tag/3.0.0)) [See instructions to upgrade your Mina node](/node-operators/requirements)