From c94583683874de977ad9ad1d6c99f889807f0ced Mon Sep 17 00:00:00 2001 From: Satyam Bansal Date: Tue, 16 Jan 2024 12:00:06 +0530 Subject: [PATCH 1/7] Fix square root example for o1js Square root of `81` with o1js will not be `9`, it will be `28948022309329048855892746252171976963363056481941560715954676764349967630328` --- docs/zkapps/o1js/basic-concepts.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/zkapps/o1js/basic-concepts.md b/docs/zkapps/o1js/basic-concepts.md index cd39275a9..5806d1af1 100644 --- a/docs/zkapps/o1js/basic-concepts.md +++ b/docs/zkapps/o1js/basic-concepts.md @@ -116,7 +116,7 @@ x = x.sub(1); // x = 6 x = x.mul(3); // x = 18 x = x.div(2); // x = 9 x = x.square(); // x = 81 -x = x.sqrt(); // x = 9 +x = x.sqrt(); // x = 28948022309329048855892746252171976963363056481941560715954676764349967630328 let b = x.equals(8); // b = Bool(false) b = x.greaterThan(8); // b = Bool(true) From 87b68c750d1b7d8a3558d90d88343fb27a13cb2b Mon Sep 17 00:00:00 2001 From: Gregor Mitscha-Baude Date: Tue, 16 Jan 2024 18:40:03 +0100 Subject: [PATCH 2/7] Update docs/zkapps/o1js/basic-concepts.md --- docs/zkapps/o1js/basic-concepts.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/zkapps/o1js/basic-concepts.md b/docs/zkapps/o1js/basic-concepts.md index 5806d1af1..3dc4021e6 100644 --- a/docs/zkapps/o1js/basic-concepts.md +++ b/docs/zkapps/o1js/basic-concepts.md @@ -116,7 +116,7 @@ x = x.sub(1); // x = 6 x = x.mul(3); // x = 18 x = x.div(2); // x = 9 x = x.square(); // x = 81 -x = x.sqrt(); // x = 28948022309329048855892746252171976963363056481941560715954676764349967630328 +x = x.sqrt(); // x = -9 let b = x.equals(8); // b = Bool(false) b = x.greaterThan(8); // b = Bool(true) From 467cb8697f964e89514cc2a3a802cb7e80bc9f13 Mon Sep 17 00:00:00 2001 From: Kadircan Bozkurt <67785258+kadirchan@users.noreply.github.com> Date: Thu, 18 Jan 2024 17:01:22 +0300 Subject: [PATCH 3/7] Correction of some part of codes The parts in the tutorial did not match each other in some places. I corrected these parts as done in https://github.com/o1-labs/docs2/tree/main/examples/zkapps/07-oracles. --- docs/zkapps/tutorials/07-oracle.mdx | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/docs/zkapps/tutorials/07-oracle.mdx b/docs/zkapps/tutorials/07-oracle.mdx index 722a561b3..60f3aa341 100644 --- a/docs/zkapps/tutorials/07-oracle.mdx +++ b/docs/zkapps/tutorials/07-oracle.mdx @@ -170,23 +170,23 @@ $ rm src/Add.test.ts $ rm src/interact.ts ``` -1. Create the `CreditScoreOracle.ts` file and generate the corresponding test file: +1. Create the `OracleExample.ts` file and generate the corresponding test file: ```sh -$ zk file CreditScoreOracle +$ zk file OracleExample ``` 1. Change `index.ts` to: ```ts -import { CreditScoreOracle } from './CreditScoreOracle.js'; +import { OracleExample } from './OracleExample.js'; -export { CreditScoreOracle }; +export { OracleExample }; ``` ### Write the smart contract -Paste the following content into the `/src/CreditScoreOracle.ts` file: +Paste the following content into the `/src/OracleExample.ts` file: ```ts @@ -238,7 +238,7 @@ This completes the basic setup for the smart contract. For details on the `init( The smart contract stores the public key for the oracle that you retrieve data from as on-chain state. This makes the public key available when end users run the smart contract. The smart contract then uses this public key to verify the signature of the data to confirm it came from the expected source. -In the `/src/CreditScoreOracle.ts` file: +In the `/src/OracleExample.ts` file: ```ts // Define contract state @@ -345,9 +345,9 @@ this.emitEvent('verified', id); ## Test your smart contract -When you ran the `zk file CreditScoreOracle` command, the zkApp CLI automatically generated a test file called `CreditScoreOracle.test.ts`. +When you ran the `zk file OracleExample` command, the zkApp CLI automatically generated a test file called `OracleExample.test.ts`. -To add tests, paste the following code in the `CreditScoreOracle.test.ts` file: +To add tests, paste the following code in the `OracleExample.test.ts` file: ```ts import { OracleExample } from './OracleExample'; @@ -509,7 +509,7 @@ describe('OracleExample', () => { To run the tests: -1. Save the `CreditScoreOracle.test.ts` file. +1. Save the `OracleExample.test.ts` file. 1. Run `npm run test`. 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. From df90aafdc83e0b61e18e9fc8e49f987e5a6b3c17 Mon Sep 17 00:00:00 2001 From: Kadircan Bozkurt <67785258+kadirchan@users.noreply.github.com> Date: Thu, 18 Jan 2024 17:20:22 +0300 Subject: [PATCH 4/7] Improvements on tutorial-08 --- docs/zkapps/tutorials/08-custom-tokens.mdx | 40 ++++++++++++++++++++++ 1 file changed, 40 insertions(+) diff --git a/docs/zkapps/tutorials/08-custom-tokens.mdx b/docs/zkapps/tutorials/08-custom-tokens.mdx index 8e4d205a4..6dc0ca2cd 100644 --- a/docs/zkapps/tutorials/08-custom-tokens.mdx +++ b/docs/zkapps/tutorials/08-custom-tokens.mdx @@ -52,6 +52,46 @@ This tutorial has been tested with: - [Mina zkApp CLI](https://github.com/o1-labs/zkapp-cli) version 0.13.0 - [o1js](https://www.npmjs.com/package/o1js) version 0.13.0 +## Create the project + +1. Create or change to a directory where you have write privileges. +1. Create a project by using the `zk project` command: + + ```sh + $ zk project 08-custom-tokens + ``` + + The `zk project` command has the ability to scaffold the UI for your project. For this tutorial, select `none`: + + ``` + ? Create an accompanying UI project too? … + next + svelte + nuxt + empty + ❯ none + ``` +## Prepare the project + +1. Change to the project directory, delete the existing files, and create a new `src/BasicTokenContract` smart contract, and a `index.ts` file: + + ```sh + $ cd 08-custom-tokens + $ rm src/Add.ts + $ rm src/Add.test.ts + $ rm src/interact.ts + $ zk file src/BasicTokenContract + $ touch src/index.ts + ``` + +1. Edit `index.ts` to import and export your new smart contract: + + ```ts + import { BasicTokenContract } from './BasicTokenContract.js'; + + export { BasicTokenContract }; + ``` + ## Basic Token Example To create a token manager smart contract, create a normal smart contract whose methods call special functions that manipulate tokens. From d51df06e773428f90aeb0ed1006adb2ad5eb371c Mon Sep 17 00:00:00 2001 From: Barrie Byron Date: Fri, 19 Jan 2024 16:23:51 -0500 Subject: [PATCH 5/7] prep how-zkapps-work for HF audit --- docs/zkapps/how-zkapps-work.mdx | 58 +++++++++++++++------------------ 1 file changed, 27 insertions(+), 31 deletions(-) diff --git a/docs/zkapps/how-zkapps-work.mdx b/docs/zkapps/how-zkapps-work.mdx index 65c870398..c608c9aae 100644 --- a/docs/zkapps/how-zkapps-work.mdx +++ b/docs/zkapps/how-zkapps-work.mdx @@ -5,7 +5,7 @@ description: In-depth explanation of how zkApps work. The structure of a zkApp, keywords: - zkApps - smart contracts - - zero-knowledge proofs + - zero knowledge proofs - prover function - verifier function - mina network @@ -24,18 +24,16 @@ zkApp programmability is not yet available on the Mina Mainnet. You can get star 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 Mina zkApp CLI. +zkApps are written in TypeScript using the zkApp CLI. A zkApp consists of two parts: - A smart contract - A user interface (UI) for users to interact with the zkApp -
Diagram showing two parts of a zkApp
- - The term _smart contract_ refers to the code written with o1js. - The term _zkApp_ refers to the UI + the smart contract. @@ -44,9 +42,9 @@ A zkApp consists of two parts: 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 by using o1js and generates a prover function and a corresponding verifier function that are derived during the build process. +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 a 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. @@ -54,13 +52,13 @@ When interacting with a zkApp UI, users enter any data (for example, buy ABC for Diagram showing private and public inputs to prover function to create zero knowledge proof -Both private inputs and public inputs represent data that must be provided to the prover function when it runs in the user's web browser. +Private and public inputs represent data that must be provided to the prover function when it runs in the end user's web browser. Private inputs are not required again. Because public inputs must also be provided to the verifier function when it runs on the Mina network, public inputs are not used for data that you want to remain private. The verifier function validates whether a zero knowledge proof successfully passes all the constraints defined in the prover function. The verifier function _always_ runs quickly and efficiently, irrespective of the prover function's complexity. -Within the Mina network, Mina acts as the verifier and runs the verifier function. +Within the Mina network, Mina acts as the verifier and runs the verifier function.
Diagram showing verifier function validation @@ -68,40 +66,38 @@ Within the Mina network, Mina acts as the verifier and runs the verifier functio ## Prover Function and Verification Key -After you write your smart contract, run 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: - Run a prover function to run your smart contract - Generate a verification key to deploy your smart contract -While the prover function runs in a user's web browser, 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. A verification key is required to create a zkApp account. +While the prover function runs in an end user's web browser, 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. A verification key is required to create a zkApp account. You can also use the verifier function or verification key to verify proofs off-chain. ## Deploy a smart contract -Smart contracts are deployed to the Mina network using the Mina zkApp CLI. The deployment process sends a transaction that contains the verification key, an output of the verifier function, to an address on the Mina blockchain. - +zkApp developers use the zkApp CLI to deploy smart contracts to the Mina network. The deployment process sends a transaction that contains the verification key that is an output of the verifier function to an address on the Mina blockchain.
Diagram showing deployment of a Mina zkApp smart contract
- When a Mina address contains a verification key, it acts as a zkApp account. A regular Mina account can receive any transactions. -You can specify [permissions](/zkapps/o1js/permissions) so a zkApp account can successfully receive only transactions that satisfy the verifier function. +You can specify [permissions](/zkapps/o1js/permissions) so a zkApp account can successfully receive only the transactions that satisfy the verifier function. -Any transactions that do not pass the verifier function are rejected by the Mina network. +The Mina network rejects any transactions that do not pass the verifier function. -When you deploy to a new Mina address, the Mina Protocol charges a 1 MINA fee for account creation. This fee is unrelated to zkApps and helps to prevent Sybil or denial of service attacks. +When you deploy a zkApp to a new Mina address, the Mina Protocol charges a 1 MINA fee for account creation. This fee is unrelated to zkApps and helps to prevent Sybil or denial of service attacks. ## Deploy a zkApp UI 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 of your users. +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. Diagram of a zkApp that includes JavaScript and the UI @@ -109,29 +105,29 @@ Your website must contain the JavaScript `smart_contract.js` file that you gener ## How users interact with a zkApp -To use a zkApp, users must [Install a Wallet](../using-mina/install-a-wallet) that supports interactions with zkApps. +To use a zkApp, end users must [Install a Wallet](../using-mina/install-a-wallet) that supports interactions with zkApps. -After a zkApp is deployed to a host (for example, mycoolzkapp.com), users can interact with it: +After a zkApp is deployed to a host (for example, mycoolzkapp.com), end users can interact with it: -1. User visits mycoolzkapp.com. -1. User interacts with the zkApp and enters any data as required. (For example, if this were an automated market maker, the user might specify to buy x amount of ABC at y price.) +1. The user visits mycoolzkapp.com. +1. The user interacts with the zkApp and enters the required data. For example, if this were an automated market maker, the user might specify to buy x amount of ABC at y price. 1. The prover function in the zkApp generates a zero knowledge proof locally using the data entered by the user. This data can be either: - - Private, the data is never seen by the blockchain + - 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. - Additionally, 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. User selects “submit to chain” in the zkApp UI. - - The user confirms the transaction on their wallet, such as a browser extension wallet. - - The wallet signs the transaction that contains the proof and the associated description of state to update. + 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 wallet signs the transaction containing the proof and the associated description of state to update. - The wallet sends the transaction to the Mina network. -1. The Mina network receives this transaction and verifies that the proof successfully passes the verifier method listed on the zkApp account. If the network accepts this transaction, then this proof and the requested state changes are valid and are allowed to update the zkApp state. +1. The Mina network receives this transaction and verifies that the proof successfully passes the verifier method listed on the zkApp account. If the network accepts this transaction, this proof and the requested state changes are valid and are allowed to update the zkApp state. -The user's privacy is maintained because their interaction occurs locally in a web browser using JavaScript on the client. +The end user's privacy is maintained because their interaction occurs locally in a web browser using JavaScript on the client. -### How state is updated on chain +### How state is updated on-chain -The zkApp account gets updated on chain. +The zkApp account gets updated on-chain. When the prover function runs in a web browser, the smart contract outputs a proof and some associated data called "account updates" that are sent to a zkApp address as part of the transaction. The account updates are a JSON plain text description that describes how to update the state on a zkApp account. @@ -159,4 +155,4 @@ When the zkApp runs in a user's web browser, it can insert state to an external ### Keep going -On the next page, learn [How to write a zkApp](how-to-write-a-zkapp). +See [zkApps Getting Started](/zkapps/getting-started-zkapps). From 04aa14ac23c93600e4b17b7629a71f456bde1400 Mon Sep 17 00:00:00 2001 From: barriebyron Date: Fri, 19 Jan 2024 17:00:48 -0500 Subject: [PATCH 6/7] change sidebar title --- docs/zkapps/index.mdx | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/zkapps/index.mdx b/docs/zkapps/index.mdx index 47e959d9d..39f3e0dc0 100644 --- a/docs/zkapps/index.mdx +++ b/docs/zkapps/index.mdx @@ -1,6 +1,6 @@ --- title: zkApps Overview -sidebar_label: Overview +sidebar_label: zkApps Overview hide_title: true description: zkApps (zero knowledge apps) are Mina Protocol smart contracts powered by zero knowledge proofs, specifically using zk-SNARKs. Use this quickstart guide to deploy zkApps and resources for learning TypeScript. keywords: @@ -26,7 +26,7 @@ zkApp programmability is not yet available on the Mina Mainnet. You can get star
Terminal screenshot of Mina’s zkApp CLI command-line interface.
@@ -37,9 +37,9 @@ zkApp programmability is not yet available on the Mina Mainnet. You can get star zkApps (zero knowledge apps) are Mina Protocol smart contracts powered by zero knowledge proofs, specifically using zk-SNARKs. -zkApps use an **off-chain execution** and mostly **off-chain state** model. This allows for private computation and state that can be either private or public. +zkApps use an **off-chain execution** and mostly **off-chain state** model. This architecture allows for private computation and state that can be either private or public. -zkApps can perform arbitrarily-complex computations off chain while incurring only a flat fee to send the resulting zero-knowledge proof to the chain for verification of this computation, as opposed to other blockchains that run computations on chain and use a variable gas-fee based model. +zkApps can perform arbitrarily-complex computations off-chain while incurring only a flat fee to send the resulting zero knowledge proof to the chain for verification of this computation. This cost saving benefit is in contrast to other blockchains that run computations on-chain and use a variable gas-fee based model.
-Learn more on [How zkApps Work](./zkapps/how-zkapps-work). +To learn more, see [How zkApps Work](./zkapps/how-zkapps-work). ### TypeScript From f77a960e00f46a8ac40a100433f96cf755f45c0f Mon Sep 17 00:00:00 2001 From: barriebyron Date: Fri, 19 Jan 2024 17:04:26 -0500 Subject: [PATCH 7/7] zkApp CLI --- docs/zkapps/zkapps-for-ethereum-developers.mdx | 10 ++++------ 1 file changed, 4 insertions(+), 6 deletions(-) diff --git a/docs/zkapps/zkapps-for-ethereum-developers.mdx b/docs/zkapps/zkapps-for-ethereum-developers.mdx index 45dff6122..906b56479 100644 --- a/docs/zkapps/zkapps-for-ethereum-developers.mdx +++ b/docs/zkapps/zkapps-for-ethereum-developers.mdx @@ -31,8 +31,8 @@ on privacy and scalability. The Mina Protocol works differently. It verifies transactions (and previous blocks) cryptographically using recursive zero-knowledge proofs. Smart contract -code is written in TypeScript and executes off chain. Mina nodes only need to -verify a small proof in order to validate the associated execution. Better +code is written in TypeScript and executes off chain. Mina nodes need to +verify only a small proof in order to validate the associated execution. Better still, the proof does not reveal any information about the underlying computation, meaning developers can choose whether their inputs and outputs should be public or private, depending on the requirements of their application. @@ -71,7 +71,7 @@ should be public or private, depending on the requirements of their application. Developer Tooling New developer tools with unusual patterns like Hardhat, and Truffle are needed in order to manage the deployment of Ethereum smart contracts. - The Mina zkApp CLI manages scaffolding, linting, testing, and deployment using common JavaScript/TypeScript tools you are already familiar with. + The zkApp CLI manages scaffolding, linting, testing, and deployment using common JavaScript/TypeScript tools you are already familiar with. Scaling @@ -121,9 +121,7 @@ export class Add extends SmartContract { } ``` -## FAQ - -### How does Mina bridge to Ethereum? +## How does Mina bridge to Ethereum? Mina proofs are small and easy to verify; this means that any Turing complete blockchain (like Ethereum) can validate the entire Mina state in a single