![]({require("@site/static/img/homepage/zkapp_developers.png").default})
diff --git a/docs/mina-faq.mdx b/docs/mina-faq.mdx
deleted file mode 100644
index bb757756c..000000000
--- a/docs/mina-faq.mdx
+++ /dev/null
@@ -1,85 +0,0 @@
-# FAQ
-
-
-
-## General Questions
-
-
-
-
-### Why did you develop a new protocol?
-
-The reason for developing a new protocol instead of offering services to other blockchains is because adding SNARKs after the fact to a Layer 1 project is not trivial. Even basic operations need to be optimized for performance inside a SNARK, and existing implementations are not able to be retrofit as such. If we look at hashing functions for example, SHA256 (used by Bitcoin) or Keccak (used by Ethereum) are extremely expensive inside a SNARK circuit, but Poseidon (what Mina uses) is optimized for performance. This and many other technical considerations make it infeasible to easily add recursive SNARKs to existing Layer 1 blockchains, without entirely overhauling the base protocol.
-
-#### How does Mina verify the current state of the chain without having historical data? How do you audit a transaction if you only keep a proof of the blockchain?
-
-The average user does not need to know the entire transaction history. For
-example, when you make a purchase using a dollar, you also don't need to know
-where that dollar came from and how it was spent before arriving in your wallet.
-Other blockchains depend on the transaction history to verify that the current
-state is valid. Mina is using zk-SNARKs to prove that (see
-[this video](https://www.youtube.com/watch?v=eWVGATxEB6M) where co-founder Izaak
-Meckler explains Mina's recursive use of zk-SNARKs). This enables Mina to become
-the world's lightest blockchain and to always be accessible for all.
-
-For cases where a user wants to prove the inclusion of past transactions, Mina
-has a feature called the receipt chain. Each account has its own receipt chain,
-represented in the current state by a hash. When a user sends a transaction from
-an account, that transaction modifies the receipt chain of the account, to be
-the hash of the previous receipt chain, and the new transaction (a merkle list).
-This allows users to prove a particular transaction was sent from their account.
-
-For programs, Mina uses a different programming paradigm than other chains -
-instead of being able to reference past history, you can only reference the
-current state. This is akin to a filesystem that allows writing, deleting, and
-overwriting data, rather than the “append only” filesystem seen in the usual
-blockchain. This is intentional, so that Mina will always be lightweight, and
-sustainable - once the proof is available to stand in for the history, storing
-the history is more for archival or reference purposes, rather than security or
-necessary use.
-
-The programming paradigm in Mina will be designed to reflect this - right now
-Mina has minimal data per account. Programs storing more data will have to pay
-some amount for that data, likely when added with something like state rent.
-
-Clients that do seek to have the full archival history can operate as archive
-nodes, to store the full history as well. However, because unlike other
-blockchains the full history isn’t necessary for any actions that can be
-performed on chain, these are more for data analysis purposes than anything
-else.
-
-
-#### Does Mina support shielded transactions, like in Zcash?
-
-No, Mina does not natively implement privacy features at the moment. However,
-privacy is a key consideration for cryptocurrencies, and is also on the
-development roadmap.
-
-#### Can I run the Mina daemon as a service
-
-See here for information about using launchd or systemd with Mina.
-
-## SNARKs and Snark Workers
-
-#### Is generating SNARKs similar to Proof-of-Work (PoW) mining?
-
-No, they are different in several ways:
-
-- SNARK work is deterministic, while PoW mining requires randomly calculating
- hashes to try and solve a puzzle. There is no luck element in SNARK work — if
- a snark worker wants to generate a SNARK of a transaction, they only need to
- generate the proof once. This means SNARK work is much less expensive and
- environmentally wasteful, as the compute is all spent towards a productive
- goal.
-- There is no difficulty increase for SNARK work, as there is with PoW mining.
- In fact, as SNARK constructions, and proof generation times improve, the
- difficulty may actually decrease.
-- SNARK work is not directly involved in consensus. Snark workers play no role
- in determining the next state of the blockchain. Their role is to simply
- generate SNARKs of transactions observed in the network
-- As a snark worker, there is no requirement for uptime. PoW miners need to run
- their rigs non-stop to ensure they don't miss out on a potential block. Snark
- workers can come online and offline as they please — it is more like Uber,
- where there will always be work to be done, and nobody needs to say ahead of
- time when they want to work.
-
diff --git a/docs/node-developers/graphql-api.mdx b/docs/node-developers/graphql-api.mdx
index 7282141d0..5c74aa637 100644
--- a/docs/node-developers/graphql-api.mdx
+++ b/docs/node-developers/graphql-api.mdx
@@ -19,17 +19,21 @@ A new version of Mina Docs is coming soon! This page will be rewritten.
:::
-The Mina daemon exposes a [GraphQL API](https://graphql.org/) used to request information from and submit commands to a running node. By default, an HTTP server runs on port `3085`, though this may be configured by passing the `-rest-port` flag to the daemon startup command.
+The Mina daemon exposes a [GraphQL API](https://graphql.org/) used to request information from and submit commands to a running node.
-To use the GraphQL API, connect your GraphQL client to `http://localhost:3085/graphql` or open in your browser to utilize the [GraphiQL IDE](https://github.com/graphql/graphiql). By default, for security, only connections from `localhost` are permitted. To listen on all interfaces, add the `-insecure-rest-server` flag to the daemon startup command.
+To use the GraphQL API, connect your GraphQL client to `http://localhost:3085/graphql` or open in your browser to use the [GraphiQL IDE](https://github.com/graphql/graphiql).
-In addition to information about the running node, the GraphQL API can return data about the network's latest blocks. However, as the blockchain's historical state is not persisted in Mina, only blocks in the node's transition frontier are returned, i.e., the last `k` blocks. For other historical data, use the archive node that is designed to retain and retrieve historical data.
+- By default, an HTTP server runs on port `3085`. You can configure a different port, use the `-rest-port` flag with the daemon startup command.
-The full Mina GraphQL schema is available [here](https://github.com/MinaProtocol/mina/blob/develop/graphql_schema.json).
+- The default security permits only connections from `localhost`. To listen on all interfaces, add the `-insecure-rest-server` flag to the daemon startup command.
+
+In addition to information about the running node, the GraphQL API can return data about the network's latest blocks. However, as the blockchain's historical state is not persisted in Mina, only blocks in the node's transition frontier are returned, i.e., the last `k` blocks. For other historical data, use the [Archive Node](/node-operators/archive-node) that is designed to retain and retrieve historical data.
+
+The full Mina GraphQL schema is available [https://github.com/MinaProtocol/mina/blob/develop/graphql_schema.json](https://github.com/MinaProtocol/mina/blob/develop/graphql_schema.json).
### Queries
-The Mina GraphQL API has a number of [queries](https://docs.minaprotocol.com/node-operators/querying-data) to extract data from a running node. [GraphQL queries](https://graphql.org/learn/queries/) allow specifying the data to be returned in the response. For example to get the latest block and creator information known to the daemon:
+The Mina GraphQL API has a number of [queries](/node-operators/querying-data) to extract data from a running node. [GraphQL queries](https://graphql.org/learn/queries/) allow specifying the data to be returned in the response. For example, to get the latest block and creator information known to the daemon:
```
query {
@@ -49,7 +53,7 @@ query {
}
```
-The following query requests all pending transactions in the [transaction pool](#) together with their fees. This query may be used to generate an estimate of a suggested fee for a transaction:
+The following query requests all pending transactions in the transaction pool together with their fees. This query can be used to generate an estimate of a suggested fee for a transaction:
```
query {
@@ -88,15 +92,11 @@ curl -d '{"query": "{
}"}' -H 'Content-Type: application/json' http://localhost:3085/graphql
```
-### Mutations:
+### Mutations
GraphQL mutations modify the running node in some way. For example, mutations may be used to send a payment, create a new account, or to add additional peers.
-:::tip
-
-Consult the [GraphQL schema](https://docs.minaprotocol.com/graphql-docs/mutation.doc.html) for all available mutations.
-
-:::
+Consult the GraphQL schema for all available mutations.
Adding a new peer:
@@ -110,7 +110,7 @@ mutation {
}
```
-Update a snark worker to use a fee of 0.1 mina:
+Update a SNARK worker to use a fee of 0.1 MINA:
```
mutation {
@@ -118,9 +118,9 @@ mutation {
}
```
-### Subscriptions:
+### Subscriptions
-A GraphQL [subscription](https://docs.minaprotocol.com/graphql-docs/subscription.doc.html) allows a GraphQL client to have data pushed to it when an event occurs. In Mina, there are subscriptions for:
+A GraphQL subscription allows a GraphQL client to have data pushed to it when an event occurs. In Mina, there are subscriptions for:
- _newSyncUpdate_ - occurs when the sync status of the node changes.
- _newBlock_ - occurs when a new block is received.
@@ -143,14 +143,14 @@ subscription {
}
```
-The new block subscription may also be limited to only return new blocks created by a defined public key with the `publicKey` argument.
+The new block subscription can also be limited to return only new blocks created by a defined public key with the `publicKey` argument.
### GraphQL Public Proxy
-While exposing the GraphQL API to the internet is not recommended, an implementation of a [GraphQL proxy](https://github.com/MinaProtocol/mina/tree/master/automation/services/graphql-public-proxy) is available that removes the queries that pose a threat but still allows querying of the node's data from a public endpoint.
+While exposing the GraphQL API to the internet is not recommended, an implementation of a [GraphQL proxy](https://github.com/MinaProtocol/mina/tree/master/automation/services/graphql-public-proxy) is available that removes the queries that pose a threat, but still allows querying of the node's data from a public endpoint.
### Resources
-- [5-minute introduction video on Mina GraphQL API](http://bit.ly/GraphQLAPIin5)
+- [5-minute introduction video on Mina GraphQL API](http://bit.ly/GraphQLAPIin5) Coda
- [First steps with the Mina GraphQL API](https://garethtdavies.com/crypto/first-steps-with-coda-graphql-api.html)
- [Introduction to GraphQL](https://graphql.org/learn/)
diff --git a/docs/node-operators/archive-node.mdx b/docs/node-operators/archive-node.mdx
index 793761aa7..930d36be6 100644
--- a/docs/node-operators/archive-node.mdx
+++ b/docs/node-operators/archive-node.mdx
@@ -106,6 +106,143 @@ To run a local archive node to run it in the foreground for testing:
To connect to an archive process on another machine, specify a hostname with `localhost:3086`.
+## Set up the archive node using Docker
+
+To get started with installing and running the archive node using Docker, follow the steps below.
+
+1. Install Docker on your machine. For more information, see [Docker](https://docs.docker.com/get-docker/).
+
+2. Pull the archive node image from Docker Hub.
+
+ ```sh
+ docker pull minaprotocol/mina-archive:1.3.0-9b0369c-bullseye
+ ```
+
+3. Pull and install the postgres image from Docker Hub.
+
+ ```sh
+ docker pull postgres
+ ```
+
+4. Start the postgres container and expose it's networking to other containers.
+
+ ```sh
+ docker run --name postgres -p 5432:5432 -e POSTGRES_PASSWORD=postgres -d postgres
+ ```
+
+5. Create a local postgres database called `archive`.
+
+ ```sh
+ docker exec -it postgres createdb -U postgres archive
+ ```
+
+6. Load the mina archive schema into the archive database.
+
+ ```sh
+ curl -Ls https://raw.githubusercontent.com/MinaProtocol/mina/master/src/app/archive/create_schema.sql | docker exec -i postgres psql -U postgres -d archive
+ ```
+
+7. Create a local directory to store the archive node data.
+
+ ```sh
+ mkdir -p /tmp/archive
+ ```
+
+8. Start the archive node.
+
+ ```sh
+ docker run \
+ --name archive \
+ -p 3086:3086 \
+ -v /tmp/archive:/data \
+ minaprotocol/mina-archive:1.3.0-9b0369c-bullseye \
+ mina-archive run \
+ --postgres-uri postgres://postgres:postgres@postgres:5432/archive \
+ --server-port 3086
+
+ ```
+
+9. Start the mina daemon and connect it to the archive process that you started on port 3086:
+
+ ```
+ mina daemon \
+ .....
+ --archive-address 3086\
+ ```
+
+## Set up the archive node using Docker Compose
+
+Docker Compose is a tool for defining and running multi-container Docker applications.
+With Compose, you use a YAML file to configure your application's services. Then, with a single command, you create and start all the services from your configuration.
+
+To run the archive node using Docker Compose:
+
+1. Install Docker on your machine. For more information, see [Docker](https://docs.docker.com/get-docker/).
+
+2. Install Docker Compose on your machine. For more information, see [Docker Compose](https://docs.docker.com/compose/install/).
+
+3. Pull the archive node image from Docker Hub.
+
+ ```sh
+ docker pull minaprotocol/mina-archive:1.3.0-9b0369c-bullseye
+ ```
+
+4. Pull and install the postgres image from Docker Hub.
+
+ ```sh
+ docker pull postgres
+ ```
+
+5. Create a local directory to store the archive node data.
+
+ ```sh
+ mkdir -p /tmp/archive
+ ```
+
+6. Create a `docker-compose.yml` file with the following contents:
+
+ ```yml
+ version: '3.8'
+ services:
+ postgres:
+ image: postgres
+ environment:
+ POSTGRES_PASSWORD: postgres
+ volumes:
+ - './postgres-data:/var/lib/postgresql/data'
+ ports:
+ - '5432:5432'
+ archive:
+ image: 'minaprotocol/mina-archive:1.3.0-9b0369c-bullseye'
+ command: >-
+ mina-archive run --postgres-uri
+ postgres://postgres:postgres@postgres:5432/archive --server-port 3086
+ volumes:
+ - '/tmp/archive:/data'
+ ports:
+ - '3086:3086'
+ depends_on:
+ - postgres
+ ```
+
+7. Start the archive node.
+
+ ```sh
+ # If you are running Docker Compose V1:
+ docker-compose up
+
+ # If you are running Docker Compose V2:
+ docker compose up
+ ```
+
+8. Start the mina daemon and connect it to the archive process that you started on port 3086:
+
+ ```
+ mina daemon \
+ .....
+ --archive-address 3086\
+ ```
+
## Using the Archive Node
Take a look at the tables in the database.
diff --git a/docs/node-operators/connecting-to-devnet.mdx b/docs/node-operators/connecting-to-devnet.mdx
index 756d2c7fa..d8c5a226e 100644
--- a/docs/node-operators/connecting-to-devnet.mdx
+++ b/docs/node-operators/connecting-to-devnet.mdx
@@ -91,7 +91,7 @@ EXTRA_FLAGS=" --block-producer-key - You see the following output: ```sh diff --git a/docs/zkapps/how-to-test-a-zkapp.mdx b/docs/zkapps/how-to-test-a-zkapp.mdx index efc102052..fbd5aa454 100644 --- a/docs/zkapps/how-to-test-a-zkapp.mdx +++ b/docs/zkapps/how-to-test-a-zkapp.mdx @@ -8,6 +8,7 @@ keywords: - Smart contract - Jest - Local blockchain + - Docker test --- :::info @@ -18,10 +19,23 @@ zkApp programmability is not yet available on the Mina Mainnet. You can get star # How to Test a zkApp -Writing automated tests for your smart contract is essential to ensure your code is well tested during development. All projects created using the Mina zkApp CLI include the [Jest](https://jestjs.io/) JavaScript testing framework. Although you can use any testing framework, the instructions in this document are supported for Jest. +Writing automated tests for your smart contract is essential to ensure your code is well-tested during development. + +## Test zkApps on a lightweight Mina local network + +A Docker image for Mina local networks provides a simple and efficient way to deploy and run lightweight Mina blockchain networks for testing zkApps. The `o1labs/mina-local-network` Docker image provides: + +- Genesis ledger with pre-funded accounts +- Accounts manager service +- Additional port served by reverse proxy to pass requests to the Mina daemon GraphQL endpoint so zkApps work without additional configuration +- Single commands to launch a single node or multi node network + +Pull the [o1labs/mina-local-network](https://hub.docker.com/r/o1labs/mina-local-network) image from Docker Hub. ## Writing tests for your smart contract +All projects created using the Mina zkApp CLI include the [Jest](https://jestjs.io/) JavaScript testing framework. Although you can use any testing framework, the instructions in this document are supported for Jest. + Use the Mina zkApp CLI to create tests for your smart contract. To scaffold a TypeScript file with a corresponding test file, run: diff --git a/docs/zkapps/how-to-write-a-zkapp.mdx b/docs/zkapps/how-to-write-a-zkapp.mdx index fe4c73865..914cd27ef 100644 --- a/docs/zkapps/how-to-write-a-zkapp.mdx +++ b/docs/zkapps/how-to-write-a-zkapp.mdx @@ -86,21 +86,59 @@ Examples are based on the standard project structure and provide additional file 1. Configure your zkApp: `zk config` - The command prompts guide you to add a deploy alias to your project `config.json` file. The deploy alias can be anything you want. For this example, use `berkeley`. + The command prompts guide you to add a deploy alias to your project `config.json` file. - For Berkeley Testnet, use: + The deploy alias can be anything you want. For more details, see [Deploy alias](/zkapps/tutorials/deploying-to-a-network#deploy-alias) in Tutorial 3: Deploy to a Live Network. + + For this example on Berkeley Testnet, use: + + - Deploy alias name: `berkeley` + + This example uses `berkeley`, but the deploy alias name can be anything and does not have to match the network name. - - name: `berkeley` - Mina GraphQL API URL: `https://proxy.berkeley.minaexplorer.com/graphql` - - transaction fee: `0.1` + + - Transaction fee to use when deploying: `0.1` + + - Account to pay transaction fees: Create a new fee payer pair + +1. When prompted to choose an account to pay transaction feeds, select to use a different account: + + ```sh + Use a different account (select to see options) + ``` + + If this is the first time you run the `zk config` command, you see these options: + + ```text + ❯ Recover fee payer account from an existing base58 private key + Create a new fee payer key pair + ``` + +The option to choose another account is shown only if the user has a cached fee payer account. + +1. Next, select to 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. + ``` + +1. When prompted, give an alias to your new fee payer key pair. For this example, use `sudoku`: + + ```sh + Create an alias for this account: sudoku + ``` + + Your key pairs and deploy alias are created. 1. Fund your fee payer account. - Follow the prompts to request tMINA. + Follow the prompts to request tMINA. For this example, your MINA address is populated on the Testnet Faucet. tMINA arrives at your address when the next block is produced (~3 minutes). 1. Deploy to Testnet: `zk deploy` - Follow the prompts. For details, see [how to deploy a zkApp](how-to-deploy-a-zkapp). + Follow the prompts and select the `sudoku` deploy alias. For details, see [how to deploy a zkApp](how-to-deploy-a-zkapp). ### Option B: Start your own project @@ -119,7 +157,7 @@ Examples are based on the standard project structure and provide additional file none ``` - For your selected UI framework, follow the prompts. + For your selected UI framework, follow the prompts. See [How to Write a zkApp UI](/zkapps/how-to-write-a-zkapp-ui). To see the files that were created, change to the project (whatever you called `
+
-171 {' '}
-172 Could not find a wallet. Install Auro wallet here: {auroLinkElem}
-173
-174 );
-175 }
-176
-177 let setupText = state.hasBeenSetup
-178 ? 'SnarkyJS Ready'
-179 : 'Setting up SnarkyJS...';
-180 let setup = (
-181
-182 {' '}
-183 {setupText} {hasWallet}
-184
-185 );
-186
-187 let accountDoesNotExist;
-188 if (state.hasBeenSetup && !state.accountExists) {
-189 const faucetLink =
-190 'https://faucet.minaprotocol.com/?address=' + state.publicKey!.toBase58();
-191 accountDoesNotExist = (
-192
-193 Account does not exist. Please visit the faucet to fund this account
-194
-195 {' '}
-196 [Link]{' '}
-197
-198
-199 );
-200 }
-201
-202 let mainContent;
-203 if (state.hasBeenSetup && state.accountExists) {
-204 mainContent = (
-205
-206
-213
-216 );
-217 }
-218
-219 return (
-220 Current Number in zkApp: {state.currentNum!.toString()}
-214
-215
-221 {setup}
-222 {accountDoesNotExist}
-223 {mainContent}
-224
-225 );
-226 }
+170 // -------------------------------------------------------
+171 // Refresh the current state
+172
+173 const onRefreshCurrentNum = async () => {
+174 console.log('Getting zkApp state...');
+175 setDisplayText('Getting zkApp state...');
+176
+177 await state.zkappWorkerClient!.fetchAccount({
+178 publicKey: state.zkappPublicKey!,
+179 });
+180 const currentNum = await state.zkappWorkerClient!.getNum();
+181 setState({ ...state, currentNum });
+182 console.log(`Current number in zkApp state: ${currentNum.toString()}`);
+183 setDisplayText('');
+184 };
+185
+186 // -------------------------------------------------------...
+```
+
+### Update placeholder
+Replace the `` placeholder with a UI to show the user the state of your application:
+
+```ts 186-268
+...
+186 // -------------------------------------------------------
+187 // Create UI elements
+188
+189 let hasWallet;
+190 if (state.hasWallet != null && !state.hasWallet) {
+191 const auroLink = 'https://www.aurowallet.com/';
+192 const auroLinkElem = (
+193
+194 [Link]{' '}
+195
+196 );
+197 hasWallet = (
+198
+199 Could not find a wallet. Install Auro wallet here: {auroLinkElem}
+200
+201 );
+202 }
+203
+204 const stepDisplay = transactionlink ? ( );
+205
+206 View transaction
+207
+208 ) : (
+209 displayText
+210 );
+211
+212 let setup = (
+213
+217 {stepDisplay}
+218 {hasWallet}
+219
+220 );
+221
+222 let accountDoesNotExist;
+223 if (state.hasBeenSetup && !state.accountExists) {
+224 const faucetLink =
+225 'https://faucet.minaprotocol.com/?address=' + state.publicKey!.toBase58();
+226 accountDoesNotExist = (
+227
+228 Account does not exist. Please visit the faucet to fund this account
+229
+230 [Link]{' '}
+231
+232
+233 );
+234 }
+235
+236 let mainContent;
+237 if (state.hasBeenSetup && state.accountExists) {
+238 mainContent = (
+239
+240
+254 );
+255 }
+256
+257 return (
+258
+241 Current Number in zkApp: {state.currentNum!.toString()}{' '}
+242
+243
+250
+253
+260
+266
+261 {setup}
+262 {accountDoesNotExist}
+263 {mainContent}
+264
+265
- Could not find a wallet. Install Auro wallet here: {auroLinkElem}
+ Could not find a wallet. {auroLinkElem}
);
}
@@ -225,9 +225,9 @@ export default function Home() {
'https://faucet.minaprotocol.com/?address=' + state.publicKey!.toBase58();
accountDoesNotExist = (
- Account does not exist. Please visit the faucet to fund this account
+ Account does not exist.
- [Link]{' '}
+ Visit the faucet to fund this fee payer account
);
@@ -238,7 +238,7 @@ export default function Home() {
mainContent = (
- Current Number in zkApp: {state.currentNum!.toString()}{' '}
+ Current state in zkApp: {state.currentNum!.toString()}{' '}
- ©2022 Mina. Started by O(1) Labs.
+ ©2023 Mina. Started by O(1) Labs.
diff --git a/static/img/4_select_berkeley_auro.png b/static/img/4_select_berkeley_auro.png
new file mode 100644
index 000000000..2f1f7e4c0
Binary files /dev/null and b/static/img/4_select_berkeley_auro.png differ