Update zkapp-development-frameworks.mdx #1072

JanSlobodnik · 2024-11-13T12:55:17Z

update the doc with protokit and explanation for devs to know which one to select
This update is without the decision tree image, i need push access to add images.

update without decision tree image

vercel · 2024-11-13T12:55:23Z

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Comments	Updated (UTC)
docs2	❌ Failed (Inspect)			Nov 21, 2024 5:33am

1 Skipped Deployment

Name	Status	Preview	Comments	Updated (UTC)
07-oracles	⬜️ Ignored (Inspect)	Visit Preview		Nov 21, 2024 5:33am

vercel · 2024-11-13T12:55:24Z

@JanSlobodnik is attempting to deploy a commit to the o1labs Team on Vercel.

A member of the Team first needs to authorize it.

boray · 2024-11-13T13:01:52Z

docs/zkapps/zkapp-development-frameworks.mdx


-:::
+Applications on Mina are called zkApps, and they come in a wide range of forms, including DeFi, games, state bridges, and more. However, due to Mina’s client execution model, the developer experience differs somewhat from that of other blockchain networks, such as Ethereum.


nit: "client side execution model"

boray · 2024-11-13T13:07:18Z

docs/zkapps/zkapp-development-frameworks.mdx

+  </tr>
+  <tr>
+   <td>Please note that **Protokit is in alpha**, and settlement support with reorgs is still in progress.
+<p>


no closing tag for

boray · 2024-11-13T13:11:57Z

docs/zkapps/zkapp-development-frameworks.mdx

+  <tr>
+   <td>For developers coming from the Ethereum ecosystem, think of zkApps like smart contracts that can be verified off-chain. 
+<p>
+This enables Mina to employ a client execution model, which gives Mina its scalability and privacy properties, but it can make it difficult to develop applications with concurrent users requiring a shared state. Protokit builds on top of o1js to solve these concurrency challenges.


nit: client side

boray · 2024-11-13T13:13:13Z

docs/zkapps/zkapp-development-frameworks.mdx

- [Developer documentation](/zkapps/o1js)
- [o1js repository](https://github.com/o1-labs/o1js)
- [Discord](https://discord.gg/minaprotocol)
+[o1js](https://docs.minaprotocol.com/zkapps/o1js) is the best way to author **highly-optimized ZK circuits and primitives**, but it does not provide an easy-to-use solution for managing a shared global state.


OffchainState provides an out-of-the box solution to this. It's worth mentioning here.

o1js is also the only way to interfact directly with the protocol, its "not just" a tool for primitives

I don't think we should highlight offchain state as a serious way to handle app state until it's out of the experimental namespace. I don't think we should make casual references to things in the docs until we're ready to stand behind them 100%.

Can we consider this closed? Jan has address Florian's comment and we're not going to include mention of OffchainState.

Its not true that OffchainState is a solution to race conditions on "shared global state" as suggested above. It only solves this for user-specific state. The thing is that you can't concurrently compute over shared global state without any form of on-chain execution. That is why we built protokit, to add that possibility to the features already existing in o1js.
If you wanted to do the same with vanilla-o1js features and then polish the DX, solve other limitations in the process and then make the system efficient, you'd pretty much end up with protokit in based sequencing mode (which is the first mode we will ship)

boray · 2024-11-13T13:18:09Z

docs/zkapps/zkapp-development-frameworks.mdx

+    1. Are you willing to trade off L1 censorship resistance and liveness guarantees for high throughput and low latency?*
+        1. Yes - Hybrid mode
+        2. No - Based mode
+2. No - o1js


Existence of OffchainState makes this tree a bit complicated than this. It's true that OffchainState is not scalable as base mode Protokit since it doesn't keep a db thus recreates the offchain state Merkle tree on-the-fly which creates an overhead. But, It's ready to use now (not production-ready) and worth mentioning in the tree.

Considering this closed.

Trivo25 · 2024-11-13T14:12:40Z

docs/zkapps/zkapp-development-frameworks.mdx


-# zkApp Development Frameworks
+Developers build zkApps with **o1js**. Developers can either use o1js directly or use o1js with **Protokit**, a framework built on top of o1js. Both options offer the full benefits of Mina’s verifiable, privacy-preserving zero knowledge proofs, but offer different tradeoffs between developer experience, performance, and decentralization.


Both options offer the full benefits of Mina’s verifiable, privacy-preserving zero knowledge proofs

Do they actually? Natively, afaik Protokit executes business logic on a server/"on-chain" - away from the client - this would render privacy-preserving not true in the default case

An example from the protokit docs:

@runtimeModule() export class Balances extends RuntimeModule<Record<string, never>> { @state() public balances = StateMap.from(PublicKey, UInt64); @runtimeMethod() public mint(canMintProof: CanMintProof, amount: UInt64) { canMintProof.verify(); this.balances.set(address, amount); } }

Seems like using a proof input would be a valid way of preserving privacy on protokit.

That's not the default tho whereas with o1js it is, because everything happens locally on the clients machine

There's a difference between opt-in and opt-out so this needs to be highlighted

With a Protokit runtime you can accomplish the same architecture patterns as with account updates, but you'll have an easier time customizing the on-chain protocol part, something that is not possible with a general purpose smart contract L1. So privacy is indeed optional, but that's actually a feature you can leverage, which mitigates the concurrency issues of current smart contracts.

So privacy is indeed optional, but that's actually a feature you can leverage, which mitigates the concurrency issues of current smart contracts.

I am not saying it isn't a feature! But a big difference that users should be made aware of, especially since the default is on-chain execution.

Is everyone ok to leave this as is? The statement is still correct - both frameworks allow for privacy. The details of how to implement for privacy can be left for deeper level docs. The key point to land here is that you can build a privacy-preserving app using either framework.

Trivo25 · 2024-11-14T03:26:43Z

docs/zkapps/zkapp-development-frameworks.mdx

+
+Protokit is built on top of o1js and simplifies the development of **zkApps with concurrent users requiring a shared state**, such as DEXes or games. Protokit is recommended for most developers.
+
+O1js is the best way to write **custom zero knowledge circuits** and construct low-level primitives on Mina, such as an NFT standard or a zkML library.


o1js not O1js

Trivo25 · 2024-11-14T03:27:22Z

docs/zkapps/zkapp-development-frameworks.mdx

+
+Developers can build zkApps either directly with **o1js**, or with **o1js** + **Protokit**.
+
+Protokit is built on top of o1js and simplifies the development of **zkApps with concurrent users requiring a shared state**, such as DEXes or games. Protokit is recommended for most developers.


Protokit is recommended for most developers.
is it? What's some examples when this is the case and when it isn't? If we recommend something we should clearly lay out the motivations

We'll remove "Protokit is recommended for most developers."

fixed (removed sentence)

Trivo25 · 2024-11-14T08:09:13Z

docs/zkapps/zkapp-development-frameworks.mdx

+   </td>
+  </tr>
+  <tr>
+   <td>For developers coming from the Ethereum ecosystem, think of zkApps like smart contracts that can be verified off-chain. 


zkApps aren't verified off-chain, they are proven off-chain and verified on-chain

Trivo25 · 2024-11-14T08:13:38Z

docs/zkapps/zkapp-development-frameworks.mdx

+
+
+
+## Protokit[](https://docs.minaprotocol.com/zkapps/zkapp-development-frameworks#protokit)


this link is broken

Trivo25 · 2024-11-14T08:15:36Z

docs/zkapps/zkapp-development-frameworks.mdx

- [Developer documentation](/zkapps/o1js)
- [o1js repository](https://github.com/o1-labs/o1js)
- [Discord](https://discord.gg/minaprotocol)
+[o1js](https://docs.minaprotocol.com/zkapps/o1js) is the best way to author **highly-optimized ZK circuits and primitives**, but it does not provide an easy-to-use solution for managing a shared global state.


o1js is also the only way to interfact directly with the protocol, its "not just" a tool for primitives

Trivo25 · 2024-11-14T08:16:36Z

docs/zkapps/zkapp-development-frameworks.mdx


-## [Protokit](https://protokit.dev/)
+o1js can be used directly on the Mina L1, and is thus limited by the L1’s throughput and latency, but maintains strong decentralization guarantees.


I don't think this is a good way to phrase this. o1js is a tool that lets you build whatever on top of Mina, you can build your own app-specific rollups that would not be limited by the L1s throughput.

I agree with @Trivo25, we should be clear in distinguishing the terminology between "general o1js" and "smart contracts / account updates"

@Trivo25 @maht0rz how would you recommend changing this sentence? We're trying to make the point here that o1js has to use L1 sequencing and therefore is constrained by L1's throughput and latency but with strong decentralization guarantees.

Trivo25 · 2024-11-14T08:18:09Z

docs/zkapps/zkapp-development-frameworks.mdx

+
+**Still can’t decide between Protokit and o1js?** 
+
+This section provides a simple decision tree x`and comparison table to help zkApp developers choose which framework to use.


tree x`and

typo?

Trivo25 · 2024-11-14T08:19:13Z

docs/zkapps/zkapp-development-frameworks.mdx

+
+![Decision Tree for zkApp devs](/img/decision-tree.png)
+
+Are you developing a zkApp with concurrent users requiring a shared state?


I am not a fan of this decision tree. It ignores many details and will, imo in most cases, point developers to the wrong tools. We should educate devs on the benefits of both options, instead of assuming their use cases will just fit into one of two buckets

We'll remove the decision tree and leave the table

removed decision tree, only table remains

45930

@JanSlobodnik

Will the protokit documentation be moving to the mina protocol docs? The part about based vs. hybrid sequencing seems like it could be its own article in the protokit docs.

Overall, what message is this change intended to deliver? I think as-written it's in quite a confusing state where it pretty explicitly recommends protokit, but still makes references to o1js to be polite. If the goal is simply to say "protokit is the app development platform for Mina", this halfway approach seems too weak. If the goal is to say "o1js and protokit are two app development platforms for Mina", then I think we should remove recommendations for one or the other, and stick to the facts. I also think a factual approach will scale better when other frameworks are added.

Also, should we expect more similar PRs for docs pages as part of an effort to clean up the marketing, or is this a one-off?

andrewferrone · 2024-11-18T12:58:24Z

@45930 yes the idea is to move the Protokit documentation to the Mina Protocol docs in the future.

This update is intended to address one of the most common questions we've heard from devs when confronted with o1js and Protokit - which should I use?

The intent was to land a few core messages:

It's not o1js or Protokit, but rather o1js directly or Protokit on top of o1js.
Protokit provides an "out-of-the-box" solution for developing apps across shared state. What types of apps are those? DEXes, lending protocols, games, most apps.
Protokit has tradeoffs though (decentralization vs. throughput and latency) and can be configured in two ways - Based and Hybrid modes - depending on the dev's requirements for decentralizations vs. throughput and latency.

The goal is to help devs choose whether to develop on o1js directly or Protokit on top of o1js. If you see specific areas that are confusing let's definitely clear them up.

45930 · 2024-11-18T14:20:39Z

@andrewferrone Thanks for the reply!

one of the most common questions we've heard from devs when confronted with o1js and Protokit - which should I use?

I see! Yeah, it makes sense that people are confused by this, but I don't think there is a simple answer.

It's not o1js or Protokit, but rather o1js directly or Protokit on top of o1js.

I love this message, no issues with this from my side

Protokit provides an "out-of-the-box" solution for developing apps across shared state. What types of apps are those? DEXes, lending protocols, games, most apps.

This seems overly prescriptive to me and it also puts a narrow view on the potential use cases for Mina. What if this message was re-written more as a comparison table that explains the properties of each option? I suppose the difference between this format and a decision tree is that it's more ambiguous and doesn't lead to a specific recommendation, but it gives devs a lot more direction about how to start making their decision.

Maybe this is too many columns, but something like this, e.g.

	o1js circuits only	o1js on Mina	Protokit on Mina (Based)	Protokit on Mina (Hybrid)
Throughput
Latency
Centralization
Infrastructure Requirements
...

andrewferrone · 2024-11-18T16:41:51Z

@45930 did you see the comparison table at the bottom of the page?

We can remove the decision tree.

What if this message was re-written more as a comparison table that explains the properties of each option? I suppose the difference between this format and a decision tree is that it's more ambiguous and doesn't lead to a specific recommendation, but it gives devs a lot more direction about how to start making their decision.

Maybe this is too many columns, but something like this, e.g.

o1js circuits only o1js on Mina Protokit on Mina (Based) Protokit on Mina (Hybrid)
Throughput
Latency
Centralization
Infrastructure Requirements
...

Update zkapp-development-frameworks.mdx

2986852

update without decision tree image

JanSlobodnik requested a review from a team as a code owner November 13, 2024 12:55

vercel bot had a problem deploying to Preview – docs2 November 13, 2024 12:57 Failure

boray reviewed Nov 13, 2024

View reviewed changes

Trivo25 reviewed Nov 13, 2024

View reviewed changes

Trivo25 reviewed Nov 14, 2024

View reviewed changes

45930 reviewed Nov 14, 2024

View reviewed changes


		:::
		Applications on Mina are called zkApps, and they come in a wide range of forms, including DeFi, games, state bridges, and more. However, due to Mina’s client execution model, the developer experience differs somewhat from that of other blockchain networks, such as Ethereum.


		# zkApp Development Frameworks
		Developers build zkApps with o1js. Developers can either use o1js directly or use o1js with Protokit, a framework built on top of o1js. Both options offer the full benefits of Mina’s verifiable, privacy-preserving zero knowledge proofs, but offer different tradeoffs between developer experience, performance, and decentralization.


		Protokit is built on top of o1js and simplifies the development of zkApps with concurrent users requiring a shared state, such as DEXes or games. Protokit is recommended for most developers.

		O1js is the best way to write custom zero knowledge circuits and construct low-level primitives on Mina, such as an NFT standard or a zkML library.


		Developers can build zkApps either directly with o1js, or with o1js + Protokit.

		Protokit is built on top of o1js and simplifies the development of zkApps with concurrent users requiring a shared state, such as DEXes or games. Protokit is recommended for most developers.




		## Protokit[](https://docs.minaprotocol.com/zkapps/zkapp-development-frameworks#protokit)


		## [Protokit](https://protokit.dev/)
		o1js can be used directly on the Mina L1, and is thus limited by the L1’s throughput and latency, but maintains strong decentralization guarantees.


		Still can’t decide between Protokit and o1js?

		This section provides a simple decision tree x`and comparison table to help zkApp developers choose which framework to use.


		![Decision Tree for zkApp devs](/img/decision-tree.png)

		Are you developing a zkApp with concurrent users requiring a shared state?

Update zkapp-development-frameworks.mdx #1072

Are you sure you want to change the base?

Update zkapp-development-frameworks.mdx #1072

Conversation

JanSlobodnik commented Nov 13, 2024

vercel bot commented Nov 13, 2024 • edited Loading

vercel bot commented Nov 13, 2024

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Trivo25 Nov 15, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

45930 left a comment

Choose a reason for hiding this comment

andrewferrone commented Nov 18, 2024

45930 commented Nov 18, 2024

andrewferrone commented Nov 18, 2024

vercel bot commented Nov 13, 2024 •

edited

Loading

Trivo25 Nov 15, 2024 •

edited

Loading