ZkProgram default example starter (#725)

Author: ymekuria

CHANGELOG.md

@@ -17,6 +17,14 @@ This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 
 ## Unreleased
 
+### Added
+
+- Adds a new ZkProgram default example that is included with CLI generated projects, coupled with a new example template UI that demonstrates an end to end flow of generating proofs with a ZkProgram, and settling the state on Mina. [#725](https://github.com/o1-labs/zkapp-cli/pull/725)
+
+### Changed
+
+- Add.ts default contract modified to verify and settle ZkProgram proofs. Interact.ts and Add.test.ts modified to generate ZkProgram proofs and settle state on Mina [#725](https://github.com/o1-labs/zkapp-cli/pull/725)
+
 ## [0.22.5](https://github.com/o1-labs/zkapp-cli/compare/v0.22.4...v0.22.5) - 2025-02-07
 
 ## [0.22.4](https://github.com/o1-labs/zkapp-cli/compare/v0.22.3...v0.22.4) - 2025-01-29

package-lock.json

@@ -1,6 +1,6 @@
 {
   "name": "zkapp-cli",
-  "version": "0.22.5",
+  "version": "0.22.6",
   "description": "CLI to create zkApps (zero-knowledge apps) for Mina Protocol",
   "homepage": "https://github.com/o1-labs/zkapp-cli/",
   "repository": {

package.json

@@ -6,18 +6,20 @@ import GradientBG from '../components/GradientBG.js';
 import styles from '../styles/Home.module.css';
 import heroMinaLogo from '../public/assets/hero-mina-logo.svg';
 import arrowRightSmall from '../public/assets/arrow-right-small.svg';
-import {fetchAccount, Mina, PublicKey} from "o1js";
-import {Add} from "../../contracts";
+import {fetchAccount, Mina, PublicKey, Field, Proof} from "o1js";
+import { Add, AddZkProgram } from "../../contracts";
 
 // We've already deployed the Add contract on testnet at this address
-// https://minascan.io/devnet/account/B62qnTDEeYtBHBePA4yhCt4TCgDtA4L2CGvK7PirbJyX4pKH8bmtWe5
-const zkAppAddress = "B62qnTDEeYtBHBePA4yhCt4TCgDtA4L2CGvK7PirbJyX4pKH8bmtWe5";
+// https://minascan.io/devnet/account/B62qnfpb1Wz7DrW7279B8nR8m4yY6wGJz4dnbAdkzfeUkpyp8aB9VCp
+const zkAppAddress = "B62qnfpb1Wz7DrW7279B8nR8m4yY6wGJz4dnbAdkzfeUkpyp8aB9VCp";
 
 export default function Home() {
   const zkApp = useRef<Add>(new Add(PublicKey.fromBase58(zkAppAddress)));
 
   const [transactionLink, setTransactionLink] = useState<string | null>(null);
   const [contractState, setContractState] = useState<string | null>(null);
+  const [zkProgramState, setZkProgramState] = useState<string | null>(null);
+  const [proof, setProof] = useState<Proof<Field, Field> | null>(null);
   const [error, setError] = useState<string | null>(null);
   const [loading, setLoading] = useState<boolean>(true);
 
@@ -28,6 +30,17 @@ export default function Home() {
       await fetchAccount({publicKey: zkAppAddress});
       const num = zkApp.current.num.get();
       setContractState(num.toString());
+      setZkProgramState(num.toString());
+
+      // Compile the AddZkProgram
+      console.log("Compiling AddZkProgram");
+      await AddZkProgram.compile();
+      
+      // Initialize the AddZkProgram with the initial state of the zkapp
+      console.log("Initialize AddZkProgram with intial contract state of zkapp");
+      const init = await AddZkProgram.init(num);
+      setProof(init.proof);
+      
 
       // Compile the contract so that o1js has the proving key required to execute contract calls
       console.log("Compiling Add contract to generate proving and verification keys");
@@ -49,18 +62,25 @@ export default function Home() {
       await fetchAccount({publicKey: PublicKey.fromBase58(walletKey)});
 
       // Execute a transaction locally on the browser
-      const transaction = await Mina.transaction(async () => {
-        console.log("Executing Add.update() locally");
-        await zkApp.current.update();
-      });
+      let hash;
+      if (proof) {
+        const transaction = await Mina.transaction(async () => {
+          console.log("Executing Add.settleState() locally");
+          await zkApp.current.settleState(proof);
+        });
 
-      // Prove execution of the contract using the proving key
-      console.log("Proving execution of Add.update()");
-      await transaction.prove();
+        // Prove execution of the contract using the proving key
+        console.log("Proving execution of Add.settleState()");
+        await transaction.prove();
 
-      // Broadcast the transaction to the Mina network
-      console.log("Broadcasting proof of execution to the Mina network");
-      const {hash} = await mina.sendTransaction({transaction: transaction.toJSON()});
+        // Broadcast the transaction to the Mina network
+        console.log("Broadcasting proof of execution to the Mina network");
+        ({ hash } = await mina.sendTransaction({
+          transaction: transaction.toJSON()
+        }));
+      } else {
+        throw Error("Proof passed to Add.settleState is null");
+      }
 
       // display the link to the transaction
       const transactionLink = "https://minascan.io/devnet/tx/" + hash;
@@ -82,7 +102,22 @@ export default function Home() {
     } finally {
       setLoading(false);
     }
-  }, []);
+  }, [proof]);
+
+  const updateZkProgram = useCallback(async () => {
+    setLoading(true);
+     
+    if (contractState && proof) {
+      // Call the AddZkProgram update method
+      console.log("Calling AddZkProgram.update");
+      const update = await AddZkProgram.update(Field(contractState), proof);
+      setProof(update.proof);
+      setZkProgramState(update.proof.publicOutput.toString())
+    } else {
+      throw Error("Proof and or ContractState passed to AddZkProgram.update is null"); 
+    }
+    setLoading(false);  
+ }, [proof]);
 
   return (
     <>
@@ -117,20 +152,39 @@ export default function Home() {
             Get started by editing
             <code className={styles.code}> app/page.tsx</code>
           </p>
-          <div className={styles.state}>
-            <div>
-              <div>Contract State: <span className={styles.bold}>{contractState}</span></div>
-              {error ? (
-                <span className={styles.error}>Error: {error}</span>
-              ) : (loading ?
-                <div>Loading...</div> :
-                (transactionLink ?
-                  <a href={transactionLink} className={styles.bold} target="_blank" rel="noopener noreferrer">
-                    View Transaction on MinaScan
-                  </a> :
-                  <button onClick={updateZkApp} className={styles.button}>Call Add.update()</button>))}
+          <div className={styles.stateContainer}>
+            <div className={styles.state}>
+              <div>
+                <div>Contract State: <span className={styles.bold}>{contractState}</span></div>
+                {error ? (
+                  <span className={styles.error}>Error: {error}</span>
+                ) : (loading ?
+                  <div>Loading...</div> :
+                  (transactionLink ?
+                    <a href={transactionLink} className={styles.bold} target="_blank" rel="noopener noreferrer">
+                      View Transaction on MinaScan
+                    </a> :
+                    <button onClick={updateZkApp} className={styles.button}>Add.settleState()</button>))}
+              </div>
             </div>
-          </div>
+            <div className={styles.state}>
+              <div>
+                <div>
+                  ZkProgram State:{" "}
+                  <span className={styles.bold}>{zkProgramState}</span>
+                </div>
+                {error ? (
+                  <span className={styles.error}>Error: {error}</span>
+                ) : loading ? (
+                  <div>Loading...</div>
+                ) : (
+                  <button onClick={updateZkProgram} className={styles.button}>
+                    AddZkProgram.update()
+                  </button>
+                )}
+              </div>
+            </div>
+          </div>          
           <div className={styles.grid}>
             <a
               href="https://docs.minaprotocol.com/zkapps"

src/lib/ui/next/customNextPage.js

@@ -75,12 +75,18 @@
   justify-items: center;
 }
 
+.stateContainer {
+  display: flex;
+  flex-direction: row;
+}
+
 .state button {
   display: block;
   margin: .5rem auto 1rem;
   background-color: rgb(255, 255, 255);
   border: 1px solid #2d2d2d;
   padding: .25rem .5rem;
+  width: 11.75rem;
   cursor: pointer;
 }
 .state button:hover {
@@ -90,7 +96,7 @@
 .state {
   padding: 0.8rem 1rem;
   gap: 0.5rem;
-  margin: 1rem;
+  margin: 1rem 1.6rem;
   background-color: rgb(255, 255, 255);
   border: 1px solid #2d2d2d;
   width: 14rem;
@@ -217,6 +223,10 @@
     grid-template-rows: repeat(4, minmax(25%, auto));
   }
 
+  .stateContainer {
+    flex-direction: column;
+  }
+
   .start {
     margin-bottom: 2rem;
     padding-left: 0.5rem;

src/lib/ui/next/styles/Home.module.css

@@ -126,7 +126,7 @@ export default {
 
       // Update this to use the address (public key) for your zkApp account.
       // To try it out, you can try this address for an example "Add" smart contract that we've deployed to
-      // Testnet B62qnTDEeYtBHBePA4yhCt4TCgDtA4L2CGvK7PirbJyX4pKH8bmtWe5.
+      // Devnet B62qnfpb1Wz7DrW7279B8nR8m4yY6wGJz4dnbAdkzfeUkpyp8aB9VCp.
       const zkAppAddress = ''
       // This should be removed once the zkAppAddress is updated.
       if (!zkAppAddress) {

src/lib/ui/nuxt/customNuxtIndex.js

@@ -11,7 +11,7 @@ export default `
 
     // Update this to use the address (public key) for your zkApp account.
     // To try it out, you can try this address for an example "Add" smart contract that we've deployed to
-    // Testnet B62qnTDEeYtBHBePA4yhCt4TCgDtA4L2CGvK7PirbJyX4pKH8bmtWe5 .
+    // Devnet B62qnfpb1Wz7DrW7279B8nR8m4yY6wGJz4dnbAdkzfeUkpyp8aB9VCp .
     const zkAppAddress = ''
     // This should be removed once the zkAppAddress is updated.
     if (!zkAppAddress) {

src/lib/ui/svelte/customPageSvelte.js

@@ -1,5 +1,6 @@
 import { AccountUpdate, Field, Mina, PrivateKey, PublicKey } from 'o1js';
 import { Add } from './Add';
+import { AddZkProgram } from './AddZkProgram';
 
 /*
  * This file specifies how to test the `Add` example smart contract. It is safe to delete this file and replace
@@ -8,7 +9,7 @@ import { Add } from './Add';
  * See https://docs.minaprotocol.com/zkapps for more info.
  */
 
-const proofsEnabled = false;
+const proofsEnabled = true;
 
 describe('Add', () => {
   let deployerAccount: Mina.TestPublicKey,
@@ -20,7 +21,10 @@ describe('Add', () => {
     zkApp: Add;
 
   beforeAll(async () => {
-    if (proofsEnabled) await Add.compile();
+    await AddZkProgram.compile({ proofsEnabled });
+    if (proofsEnabled) {
+      await Add.compile();
+    }
   });
 
   beforeEach(async () => {
@@ -45,23 +49,29 @@ describe('Add', () => {
     await txn.sign([deployerKey, zkAppPrivateKey]).send();
   }
 
-  it('generates and deploys the `Add` smart contract', async () => {
+  it('initilaizes the  `AddZKprogram`', async () => {
     await localDeploy();
-    const num = zkApp.num.get();
-    expect(num).toEqual(Field(1));
+
+    const { proof } = await AddZkProgram.init(Field(1));
+
+    expect(proof.publicOutput).toEqual(Field(1));
   });
 
-  it('correctly updates the num state on the `Add` smart contract', async () => {
+  it('correctly settles `AddZKprogram` state on the `Add` smart contract', async () => {
     await localDeploy();
+    const initialState = zkApp.num.get();
+
+    const init = await AddZkProgram.init(initialState);
+    const update = await AddZkProgram.update(initialState, init.proof);
 
-    // update transaction
+    // settleState transaction
     const txn = await Mina.transaction(senderAccount, async () => {
-      await zkApp.update();
+      await zkApp.settleState(update.proof);
     });
     await txn.prove();
     await txn.sign([senderKey]).send();
 
     const updatedNum = zkApp.num.get();
-    expect(updatedNum).toEqual(Field(3));
+    expect(updatedNum).toEqual(Field(1));
   });
 });

templates/project-ts/src/Add.test.ts

@@ -1,25 +1,23 @@
 import { Field, SmartContract, state, State, method } from 'o1js';
+import { AddProgramProof } from './AddZkProgram.js';
 
 /**
  * Basic Example
  * See https://docs.minaprotocol.com/zkapps for more info.
  *
- * The Add contract initializes the state variable 'num' to be a Field(1) value by default when deployed.
- * When the 'update' method is called, the Add contract adds Field(2) to its 'num' contract state.
+ * The Add contract verifies a ZkProgram proof and updates a 'num' state variable.
+ * When the 'settleState' method is called, the Add contract verifies a
+ * proof from the 'AddZkProgram' and saves the 'num' value to the contract state.
  *
  * This file is safe to delete and replace with your own contract.
  */
 export class Add extends SmartContract {
   @state(Field) num = State<Field>();
 
-  init() {
-    super.init();
-    this.num.set(Field(1));
-  }
-
-  @method async update() {
-    const currentState = this.num.getAndRequireEquals();
-    const newState = currentState.add(2);
-    this.num.set(newState);
+  @method async settleState(proof: AddProgramProof) {
+    proof.verify();
+    this.num.requireEquals(proof.publicInput);
+    const addProgramState = proof.publicOutput;
+    this.num.set(addProgramState);
   }
 }

templates/project-ts/src/Add.ts

@@ -0,0 +1,33 @@
+import { ZkProgram, Field, SelfProof } from 'o1js';
+
+export const AddZkProgram = ZkProgram({
+  name: 'add-program',
+  publicInput: Field,
+  publicOutput: Field,
+  methods: {
+    init: {
+      privateInputs: [],
+      async method(initialState: Field) {
+        return {
+          publicOutput: initialState,
+        };
+      },
+    },
+
+    update: {
+      privateInputs: [SelfProof],
+      async method(
+        initialState: Field,
+        previousProof: SelfProof<Field, Field>
+      ) {
+        previousProof.verify();
+        initialState.assertEquals(previousProof.publicInput);
+        return {
+          publicOutput: previousProof.publicOutput.add(Field(1)),
+        };
+      },
+    },
+  },
+});
+
+export class AddProgramProof extends ZkProgram.Proof(AddZkProgram) {}

templates/project-ts/src/AddZkProgram.ts

@@ -1,3 +1,4 @@
 import { Add } from './Add.js';
+import { AddZkProgram } from './AddZkProgram.js';
 
-export { Add };
+export { Add, AddZkProgram };