o1-labs/docs2

Docs website for the Mina Protocol.

docs2's Issues

Make the edit button HUGE in the top right on all the pages (above the minimap and be sticky)

Document how to catch and show errors during smart contract execution

To the How to Write a zkApp UI page.

Related:

• SnarkyJS issue: o1-labs/o1js#492
• SnarkyJS PR: o1-labs/o1js#470

Explain what should and should not be done in the circuit

Taken from feedback from Builders Program

Gregor: in-depth tutorials can help explain this.

Draft new Exchange FAQ

Show how to declare a parameterized smart contract

From @es92

E.g. one that can be initialized with variable merkle witness heights

This is likely to make it into one of the planned tutorials, I'd imagine. If not, we can figure out where to add it.

Use React components for version numbers?

E.g. for the Mina node. For DRYer docs.

Document SnarkyJS permissions

And document use cases:

• I want to prevent tokens from being spent by __, etc
• who can upgrade a smart contract
• how to make it non-upgradeable

Customize "copy text" JS snippet to remove line numbers and ellipsis

See the Hello World tutorial. Some text snippets contain line numbers or ellipsis, to help readers

...
10
11
12
13
14
15
...

This helps when viewing the tutorial vs the final version that is linked to on Github, but makes a mess for users who copy the code. If we have the ability to customize this JS code, we could use a regex for the start of the line to remove these.

Missing GraphQL schema link

Description

The old docs had a page that displayed the graphql schema. The new docs are missing this page, we should re-add this.

Fix copy code JS, to only remove ellipsis at the start of the line

Otherwise, it will remove the spread operator from within code too. I.e. ...Permissions.default(), becomes Permissions.default(),.

Add Svelte & Vue examples for loading smart contract in UI w/o blocking UI

See bottom of https://docs.minaprotocol.com/en/zkapps/how-to-write-a-zkapp We have an example for React currently, which is good, but should add it for other frameworks too.

Add documentation for how to use preconditions

Also, Brandon will set up a team review of precondition implementation to suggest changes.

Add security recommendations section for snapp authors

• HTTPS with HSTS enabled. Testing tool
  - Enable security warnings & notifications on their project's Github repo.
• ...
• Disclaimer

Update Custom Data Types section for struct

When struct is available
https://docs.minaprotocol.com/zkapps/how-to-write-a-zkapp#custom-data-types

Add recursion docs

Add paragraph describing how to stop further user tx's from being accepted by a snapp

• Can set it to an unprovable snark--e.g. x = 0 && x = 1.
• Describe why this would be useful--to make it "one-time use" or deprecating a snapp. The protocol does not yet support a destroy() method to destroy an account, which would remove it from the ledger

Describe how snarkyjs code creates constraints while executed

The dominant paradigm in today's zk tooling is that some user code is compiled to a zk circuit. SnarkyJS, however, works differently: The user-written JS is executed to create a circuit, not compiled.

This difference creates a lot of misconceptions about snarkyjs, for users coming from other zk ecosystems or from higher-level zk material, so we should call it out in the docs to prevent these misconceptions early on.

Create a Tutorial for how zkApp Manager Accounts and Composability work

Add section about using web workers in a UI

Fix flash of "Not found" when directly navigating to a URL

Steps to reproduce:

1. Open a new browser
2. Visit a URL such as https://docs.minaprotocol.com/zkapps/tutorials/hello-world A flash of "Not Found" will appear, before the desired content loads.

It's most likely due to client side routing, but weird that it is happening at all given it's a static site. If needed, we could also consider moving the URL redirects out of the docusaurus config and into the vercel config, which should avoid it because those occur before the request reaches the framework.

Document how to use zkApps with create-react-app

Quoting a great write-up shared by from Gordon Freeman on discord:

1. npx create-react-app --template typescript

2. npm run eject

3. add the following line to the config/webpack.config.json in the return statement
   experiments: { topLevelAwait: true },
   (on my setup it is before the line target: ['browserslist'],)

4. go to your zkapp project and type: npm link

5. go to your react app and type: npm link
   5.1. make sure that the name matches the name in your zkapp package.json
   5.2 if there is a type stuff error during import use this // @ts-ignore right before the import statement in your react app
   // @ts-ignore
   import { Multisignature } from 'zkapp-multisign'
   https://stackoverflow.com/questions/64732623/react-typescript-cannot-find-module-or-its-corresponding-type-declaration

6. if there is an import error you might have to set the file extension of your zkapp in
   /build/src/index.js manually (like this: import { Multisignature } from './Multisignature.js';) -- .js is the important part
   6.1 Don't forget to add this file extension after every build of your zkapp

Decide on and document maximum circuit size + maximum input to methods

Algolia Github Actions stopped working

Description

Looking at the Github Actions history, the algolia-search job has stopped working and failed.

It seems not to affect deployment, however.

Add section on compiling and proving smart contracts in a UI

Add recommendations on where and when to compile smart contracts in a UI to provide the best end user experience.

Tutorial idea: Reverse sealed auction

To consider. Not a must have.

Sidebar - Numbers do not scroll with menu items on a long expanded menu

Description

Before scrolling on a long menu:

After scrolling on a long menu:

It seems as though the numbers are not scrolling properly and staying aligned with the sidebar menu items.

docs - explain what can be proven and what not

Add deploy() function to the Anonymous Message Board tutorial

burnto says:
Currently if you follow the step-by-step message board tutorial, it omits discussion of deployment and implementing a deploy function, which is a pretty critical part of the development cycle.
From an issue submitted to the old docs repo: MinaProtocol/docs#232

Tagging @jackryanservia to consider this.

Tweak font styles for monospace fonts, to fit better with body content

Example:

Font size and vertical alignment are different visually

Explain setting file permission on Windows when using Docker to set up a node.

Hello,

A requirement to run a node (and verify the key pair) is that the following permissions are set. The following command is provided on the Connect to Network page, under the Docker section. (The commands are also used on the key pair generation page.)

chmod 700 ~/keys
chmod 600 ~/keys/my-wallet

Windows users can't normally run these commands, and that may pose a problem if the user decides to share a windows folder containing the keys to docker using the --bind/--volume commands. The user may face an issue where the programs throw an error that the permissions are incorrectly set.

The suggestion is to add a warning block in the docs to Windows users, informing them to use Windows Subsystem for Linux (WSL) to perform the permission changes. Modern Docker makes use of WSL, and it is assumed that it's enabled on the Windows machine using Docker.

Here is a short guide showing how to perform these steps from a windows terminal. In my case, using Powershell, but it's assumed the command line (CMD) works as well.

1. Open Powershell/CMD in the directory where the keys folder is located.
2. Type wsl -d docker-desktop to open Windows Subsystem for Linux with the docker-desktop distribution (It should be available since you installed docker). You are now in a linux environment, and can run the above commands, however, some modifications need to be done.
3. Since the active directory is the folder with the files, you can drop the ~, and you need to make sure that you only use forward / slashes. The process will look something like the following. If no error message appears, the permission change completed successfully.

PS C:\CryptoWallet> wsl docker-desktop
Desktop-name:/tmp/docker-desktop-root/mnt/host/c/CryptoWallet# chmod 700 keys
Desktop-name:/tmp/docker-desktop-root/mnt/host/c/CryptoWallet# chmod 600 keys/my-wallet

This should allow users to continue as normal with the installation and use of the mina node software.

Add composability (a.k.a. call stack) docs

Fix Google Analytics integration

It seems like the current plugin used to integrate Google Analytics @docusaurus/plugin-google-gtag, is not working correctly. To fix this, we should just insert the markup that Google Analytics looks for directly in the head and body tag manually.

Custom error messages in assertions

Add a tip describing how to create custom error messages in assertions, to the How to Write a zkApp page

Add documentation on "commutative state" (CRDT state machine)

• People think state is hard to deal with in a world with off-chain execution
  • Implement "Sequence events"
  • Document/Tutorial around using "commutative state" (CRDT state machine)
  • Create thorough documentation acknowledging that this is a complicated thing that you need to think about
  • Better document preconditions

Add Hotjar integration

We would like to have better tracking of user behavior while using the docs. Hotjar will be the chosen tool to enable this feature.

Document how to create an account using SnarkyJS

Create a Tutorial for the Eth Bridge

Fix email form in the footer to correctly submit

In the footer, we have an email submission for that lets users sign up for updates. Currently, this form does not do anything when a user submits their email form.

We need to add some behavior to submit the email to an endpoint for this flow to be finished.

Document using proofsEnabled for faster development

Possible as a tip box so it stands out, likely at end of How to Write a zkApp or in the How to Deploy a zkApp section, wherever it fits best.

Create a Tutorial on Permissions

Extend Custom Tokens Tutorial to discuss consuming tokens in a zkApp

Add docs for token proofs

Document best practices around permissions and state initialization

Per discussion with Product Eng.

Document using init() method

On the How to Write a zkApp page. To show how to use it to initialize state.

Add tip (probably) for using Circuit.log

To How to Write a zkApp page.

Docs explain multiple invocations of callback passed to `Mina.transaction`

Remove .sign() invocations in the tutorials and show the flow with proof authorization

This should be implemented after the proofsEnabled feature is released. The proofsEnabled feature will give developers the option to use proof authorization but easily turn off actual proof creation for quicker development.

FAQ: Why doesn't Mina protocol run solidity code?

Could go in the FAQ or the upcoming Snapps for Ethereum developers...or both!

Create a Tutorial for recursion

Add Mina Provider Docs

pull request WIP: #53