Fix parity between local blockchain and network APIs

CHANGELOG.md

@@ -17,6 +17,14 @@ This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 
 ## [Unreleased](https://github.com/o1-labs/o1js/compare/3b5f7c7...HEAD)
 
+### Breaking changes
+
+- Fixed parity between `Mina.LocalBlockchain` and `Mina.Network` to have the same behaviors https://github.com/o1-labs/o1js/pull/1422
+  - Changed the `TransactionId` type to `Transaction`. Additionally added `PendingTransaction` and `RejectedTransaction` types to better represent the state of a transaction.
+  - `transaction.send()` no longer throws an error if the transaction was not successful for `Mina.LocalBlockchain` and `Mina.Network`. Instead, it returns a `PendingTransaction` object that contains the error. Use `transaction.sendOrThrowIfError` to throw the error if the transaction was not successful.
+  - `transaction.wait()` no longer throws an error if the transaction was not successful for `Mina.LocalBlockchain` and `Mina.Network`. Instead, it returns either a `IncludedTransaction` or `RejectedTransaction`. Use `transaction.waitOrThrowIfError` to throw the error if the transaction was not successful.
+  - `transaction.hash()` is no longer a function, it is now a property that returns the hash of the transaction.
+
 ### Added
 
 - Support for custom network identifiers other than `mainnet` or `testnet` https://github.com/o1-labs/o1js/pull/1444

run-ci-live-tests.sh

@@ -19,6 +19,8 @@ HELLO_WORLD_PROC=$!
 DEX_PROC=$!
 ./run src/examples/fetch-live.ts --bundle | add_prefix "FETCH" &
 FETCH_PROC=$!
+./run src/tests/transaction-flow.ts --bundle | add_prefix "TRANSACTION_FLOW" &
+TRANSACTION_FLOW_PROC=$!
 
 # Wait for each process and capture their exit statuses
 FAILURE=0
@@ -43,6 +45,13 @@ if [ $? -ne 0 ]; then
   echo ""
   FAILURE=1
 fi
+wait $TRANSACTION_FLOW_PROC
+if [ $? -ne 0 ]; then
+  echo ""
+  echo "TRANSACTION_FLOW test failed."
+  echo ""
+  FAILURE=1
+fi
 
 # Exit with failure if any process failed
 if [ $FAILURE -ne 0 ]; then

src/examples/zkapps/dex/run-live.ts

@@ -35,7 +35,7 @@ const network = Mina.Network({
 });
 Mina.setActiveInstance(network);
 
-let tx, pendingTx: Mina.TransactionId, balances, oldBalances;
+let tx, pendingTx: Mina.PendingTransaction, balances, oldBalances;
 
 // compile contracts & wait for fee payer to be funded
 const senderKey = useCustomLocalNetwork
@@ -285,13 +285,15 @@ async function ensureFundedAccount(privateKeyBase58: string) {
   return { senderKey, sender };
 }
 
-function logPendingTransaction(pendingTx: Mina.TransactionId) {
+function logPendingTransaction(pendingTx: Mina.PendingTransaction) {
   if (!pendingTx.isSuccess) throw Error('transaction failed');
   console.log(
     'tx sent: ' +
       (useCustomLocalNetwork
-        ? `file://${os.homedir()}/.cache/zkapp-cli/lightnet/explorer/<version>/index.html?target=transaction&hash=${pendingTx.hash()}`
-        : `https://minascan.io/berkeley/tx/${pendingTx.hash()}?type=zk-tx`)
+        ? `file://${os.homedir()}/.cache/zkapp-cli/lightnet/explorer/<version>/index.html?target=transaction&hash=${
+            pendingTx.hash
+          }`
+        : `https://minascan.io/berkeley/tx/${pendingTx.hash}?type=zk-tx`)
   );
 }
 

src/examples/zkapps/dex/run.ts

@@ -237,7 +237,9 @@ async function main({ withVesting }: { withVesting: boolean }) {
         (USER_DX * oldBalances.total.lqXY) / oldBalances.dex.X
     );
   } else {
-    await expect(tx.send()).rejects.toThrow(/Update_not_permitted_timing/);
+    await expect(tx.sendOrThrowIfError()).rejects.toThrow(
+      /Update_not_permitted_timing/
+    );
   }
 
   /**
@@ -252,14 +254,14 @@ async function main({ withVesting }: { withVesting: boolean }) {
   });
   await tx.prove();
   tx.sign([keys.user2]);
-  await expect(tx.send()).rejects.toThrow(/Overflow/);
+  await expect(tx.sendOrThrowIfError()).rejects.toThrow(/Overflow/);
   console.log('supplying with insufficient tokens (should fail)');
   tx = await Mina.transaction(addresses.user, () => {
     dex.supplyLiquidityBase(UInt64.from(1e9), UInt64.from(1e9));
   });
   await tx.prove();
   tx.sign([keys.user]);
-  await expect(tx.send()).rejects.toThrow(/Overflow/);
+  await expect(tx.sendOrThrowIfError()).rejects.toThrow(/Overflow/);
 
   /**
    * - Resulting operation will overflow the SC’s receiving token by type or by any other applicable limits;
@@ -278,7 +280,7 @@ async function main({ withVesting }: { withVesting: boolean }) {
     );
   });
   await tx.prove();
-  await tx.sign([feePayerKey, keys.tokenY]).send();
+  await tx.sign([feePayerKey, keys.tokenY]).sendOrThrowIfError();
   console.log('supply overflowing liquidity');
   await expect(async () => {
     tx = await Mina.transaction(addresses.tokenX, () => {
@@ -289,7 +291,7 @@ async function main({ withVesting }: { withVesting: boolean }) {
     });
     await tx.prove();
     tx.sign([keys.tokenX]);
-    await tx.send();
+    await tx.sendOrThrowIfError();
   }).rejects.toThrow();
 
   /**
@@ -316,7 +318,7 @@ async function main({ withVesting }: { withVesting: boolean }) {
     dex.supplyLiquidity(UInt64.from(10));
   });
   await tx.prove();
-  await expect(tx.sign([keys.tokenX]).send()).rejects.toThrow(
+  await expect(tx.sign([keys.tokenX]).sendOrThrowIfError()).rejects.toThrow(
     /Update_not_permitted_balance/
   );
 
@@ -343,7 +345,9 @@ async function main({ withVesting }: { withVesting: boolean }) {
     });
     await tx.prove();
     tx.sign([keys.user]);
-    await expect(tx.send()).rejects.toThrow(/Source_minimum_balance_violation/);
+    await expect(tx.sendOrThrowIfError()).rejects.toThrow(
+      /Source_minimum_balance_violation/
+    );
 
     // another slot => now it should work
     Local.incrementGlobalSlot(1);
@@ -452,7 +456,7 @@ async function main({ withVesting }: { withVesting: boolean }) {
   });
   await tx.prove();
   tx.sign([keys.user, keys.user2]);
-  await expect(tx.send()).rejects.toThrow(
+  await expect(tx.sendOrThrowIfError()).rejects.toThrow(
     /Account_balance_precondition_unsatisfied/
   );
 
@@ -487,7 +491,9 @@ async function main({ withVesting }: { withVesting: boolean }) {
     dex.redeemLiquidity(UInt64.from(1n));
   });
   await tx.prove();
-  await expect(tx.sign([keys.user2]).send()).rejects.toThrow(/Overflow/);
+  await expect(tx.sign([keys.user2]).sendOrThrowIfError()).rejects.toThrow(
+    /Overflow/
+  );
   [oldBalances, balances] = [balances, getTokenBalances()];
 
   /**

src/examples/zkapps/dex/upgradability.ts

@@ -123,9 +123,9 @@ async function atomicActionsTest({ withVesting }: { withVesting: boolean }) {
   });
   await tx.prove();
 
-  await expect(tx.sign([feePayerKey, keys.dex]).send()).rejects.toThrow(
-    /Cannot update field 'delegate'/
-  );
+  await expect(
+    tx.sign([feePayerKey, keys.dex]).sendOrThrowIfError()
+  ).rejects.toThrow(/Cannot update field 'delegate'/);
 
   console.log('changing delegate permission back to normal');
 
@@ -185,9 +185,9 @@ async function atomicActionsTest({ withVesting }: { withVesting: boolean }) {
     fieldUpdate.requireSignature();
   });
   await tx.prove();
-  await expect(tx.sign([feePayerKey, keys.dex]).send()).rejects.toThrow(
-    /Cannot update field 'delegate'/
-  );
+  await expect(
+    tx.sign([feePayerKey, keys.dex]).sendOrThrowIfError()
+  ).rejects.toThrow(/Cannot update field 'delegate'/);
 
   /**
    * # Atomic Actions 3
@@ -461,9 +461,9 @@ async function upgradeabilityTests({ withVesting }: { withVesting: boolean }) {
     modifiedDex.deploy(); // cannot deploy new VK because its forbidden
   });
   await tx.prove();
-  await expect(tx.sign([feePayerKey, keys.dex]).send()).rejects.toThrow(
-    /Cannot update field 'verificationKey'/
-  );
+  await expect(
+    tx.sign([feePayerKey, keys.dex]).sendOrThrowIfError()
+  ).rejects.toThrow(/Cannot update field 'verificationKey'/);
 
   console.log('trying to invoke modified swap method');
   // method should still be valid since the upgrade was forbidden

src/examples/zkapps/hello-world/run-live.ts

@@ -59,11 +59,11 @@ let transaction = await Mina.transaction(
 transaction.sign([senderKey, zkAppKey]);
 console.log('Sending the transaction.');
 let pendingTx = await transaction.send();
-if (pendingTx.hash() !== undefined) {
+if (pendingTx.hash !== undefined) {
   console.log(`Success! Deploy transaction sent.
 Your smart contract will be deployed
 as soon as the transaction is included in a block.
-Txn hash: ${pendingTx.hash()}`);
+Txn hash: ${pendingTx.hash}`);
 }
 console.log('Waiting for transaction inclusion in a block.');
 await pendingTx.wait({ maxAttempts: 90 });
@@ -77,11 +77,11 @@ transaction = await Mina.transaction({ sender, fee: transactionFee }, () => {
 await transaction.sign([senderKey]).prove();
 console.log('Sending the transaction.');
 pendingTx = await transaction.send();
-if (pendingTx.hash() !== undefined) {
+if (pendingTx.hash !== undefined) {
   console.log(`Success! Update transaction sent.
 Your smart contract state will be updated
 as soon as the transaction is included in a block.
-Txn hash: ${pendingTx.hash()}`);
+Txn hash: ${pendingTx.hash}`);
 }
 console.log('Waiting for transaction inclusion in a block.');
 await pendingTx.wait({ maxAttempts: 90 });

src/examples/zkapps/hello-world/run.ts

@@ -27,7 +27,7 @@ txn = await Mina.transaction(feePayer1.publicKey, () => {
   AccountUpdate.fundNewAccount(feePayer1.publicKey);
   zkAppInstance.deploy();
 });
-await txn.sign([feePayer1.privateKey, zkAppPrivateKey]).send();
+await txn.sign([feePayer1.privateKey, zkAppPrivateKey]).sendOrThrowIfError();
 
 const initialState =
   Mina.getAccount(zkAppAddress).zkapp?.appState?.[0].toString();
@@ -45,7 +45,7 @@ txn = await Mina.transaction(feePayer1.publicKey, () => {
   zkAppInstance.update(Field(4), adminPrivateKey);
 });
 await txn.prove();
-await txn.sign([feePayer1.privateKey]).send();
+await txn.sign([feePayer1.privateKey]).sendOrThrowIfError();
 
 currentState = Mina.getAccount(zkAppAddress).zkapp?.appState?.[0].toString();
 
@@ -70,7 +70,7 @@ try {
     zkAppInstance.update(Field(16), wrongAdminPrivateKey);
   });
   await txn.prove();
-  await txn.sign([feePayer1.privateKey]).send();
+  await txn.sign([feePayer1.privateKey]).sendOrThrowIfError();
 } catch (err: any) {
   handleError(err, 'Account_delegate_precondition_unsatisfied');
 }
@@ -91,7 +91,7 @@ try {
     zkAppInstance.update(Field(30), adminPrivateKey);
   });
   await txn.prove();
-  await txn.sign([feePayer1.privateKey]).send();
+  await txn.sign([feePayer1.privateKey]).sendOrThrowIfError();
 } catch (err: any) {
   handleError(err, 'assertEquals');
 }
@@ -118,7 +118,7 @@ try {
     }
   );
   await txn.prove();
-  await txn.sign([feePayer1.privateKey]).send();
+  await txn.sign([feePayer1.privateKey]).sendOrThrowIfError();
 } catch (err: any) {
   handleError(err, 'assertEquals');
 }
@@ -134,7 +134,7 @@ txn2 = await Mina.transaction({ sender: feePayer2.publicKey, fee: '2' }, () => {
   zkAppInstance.update(Field(16), adminPrivateKey);
 });
 await txn2.prove();
-await txn2.sign([feePayer2.privateKey]).send();
+await txn2.sign([feePayer2.privateKey]).sendOrThrowIfError();
 
 currentState = Mina.getAccount(zkAppAddress).zkapp?.appState?.[0].toString();
 
@@ -151,7 +151,7 @@ txn3 = await Mina.transaction({ sender: feePayer3.publicKey, fee: '1' }, () => {
   zkAppInstance.update(Field(256), adminPrivateKey);
 });
 await txn3.prove();
-await txn3.sign([feePayer3.privateKey]).send();
+await txn3.sign([feePayer3.privateKey]).sendOrThrowIfError();
 
 currentState = Mina.getAccount(zkAppAddress).zkapp?.appState?.[0].toString();
 
@@ -174,7 +174,7 @@ try {
     }
   );
   await txn4.prove();
-  await txn4.sign([feePayer4.privateKey]).send();
+  await txn4.sign([feePayer4.privateKey]).sendOrThrowIfError();
 } catch (err: any) {
   handleError(err, 'assertEquals');
 }

src/index.ts

@@ -46,6 +46,12 @@ export {
 } from './lib/provable-types/merkle-list.js';
 
 export * as Mina from './lib/mina.js';
+export {
+  type Transaction,
+  type PendingTransaction,
+  type IncludedTransaction,
+  type RejectedTransaction,
+} from './lib/mina/transaction.js';
 export type { DeployArgs } from './lib/zkapp.js';
 export {
   SmartContract,
@@ -82,7 +88,7 @@ export {
 export { TokenAccountUpdateIterator } from './lib/mina/token/forest-iterator.js';
 export { TokenContract } from './lib/mina/token/token-contract.js';
 
-export type { TransactionStatus } from './lib/fetch.js';
+export type { TransactionStatus } from './lib/mina/graphql.js';
 export {
   fetchAccount,
   fetchLastBlock,

src/lib/account-update.unit-test.ts

@@ -120,7 +120,7 @@ function createAccountUpdate() {
     AccountUpdate.fundNewAccount(feePayer);
   });
   tx.sign();
-  await expect(tx.send()).rejects.toThrow(
+  await expect(tx.sendOrThrowIfError()).rejects.toThrow(
     'Check signature: Invalid signature on fee payer for key'
   );
 }

src/lib/caller.unit-test.ts

@@ -27,6 +27,6 @@ let tx = await Mina.transaction(privateKey, () => {
 });
 
 // according to this test, the child doesn't get token permissions
-await expect(tx.send()).rejects.toThrow(
+await expect(tx.sendOrThrowIfError()).rejects.toThrow(
   'can not use or pass on token permissions'
 );