From ef8ca4d734ca80c7091d7891c79e400c41ac8950 Mon Sep 17 00:00:00 2001 From: Martin Minkov Date: Mon, 11 Sep 2023 13:26:40 -0700 Subject: [PATCH 01/12] feat(docs): add Mina Signer documentation This commit introduces a new documentation file for the Mina Signer library. The documentation covers installation, usage, and examples for the library. It aims to provide developers with a comprehensive guide to integrating Mina Signer into their projects. --- docs/zkapps/mina-signer.mdx | 193 ++++++++++++++++++++++++++++++++++++ 1 file changed, 193 insertions(+) create mode 100644 docs/zkapps/mina-signer.mdx diff --git a/docs/zkapps/mina-signer.mdx b/docs/zkapps/mina-signer.mdx new file mode 100644 index 000000000..10fdf1853 --- /dev/null +++ b/docs/zkapps/mina-signer.mdx @@ -0,0 +1,193 @@ +--- +id: mina-signer +title: Mina Signer +description: TODO +--- + +Mina Signer is a NodeJS/Browser compatible JavaScript library built for the Mina Protocol. It empowers developers to sign transactions and generate keys seamlessly. One of its standout features is its capability to sign transactions offline, which can then be broadcasted to the network as and when needed. There are additional features such as signing zkApp transactions, verifying zkApp transactions, generating nullifiers, and more. + +## Installation + +To install the library, run the following command: + +```sh +npm install mina-signer +``` + +## Mina Protocol Usage + +The Mina Signer offers a wide range of features for the Mina Protocol. It can be used to generate keys, sign transactions, verify transactions, and more. Mina Signer also supports compatability between different networks, such as mainnet and testnet. + +### Specifying the network + +When initializing the Mina Signer, the network must be specified. This is done by passing the `network` parameter to the constructor. The network can be either `mainnet` or `testnet`. If no network is specified, the default network is `mainnet`. + +:::tip +If you wish to specify the current Berkeley network, the value of `testnet` should be used +::: + +```js +import Client from 'mina-signer'; +const MainnetClient = new Client({ network: 'mainnet' }); // Specify mainnet +const TestnetClient = new Client({ network: 'testnet' }); // Specify testnet (Berkeley) +``` + +### Generating keys + +With Mina Signer, generating keys is straightforward. + +```js +import Client from 'mina-signer'; +const client = new Client({ network: 'mainnet' }); // Specify mainnet +const keypair = client.genKeys(); // Generates a public and private keypair +``` + +### Signing/Verifying transactions + +The Mina Signer supports signing and verifying both transactions and stake delegations. To sign a transaction or delegation, the private key of the sender must be provided. To verify a transaction or delegation, the public key of the sender must be provided. + +#### Payments + +Payments are transactions that transfer funds from one account to another. To sign a payment, the following parameters must be provided: + +```js +import Client from 'mina-signer'; +const client = new Client({ network: 'mainnet' }); +const keypair = client.genKeys(); + +const payment = client.signPayment( + { + to: keypair.publicKey, // Public key of the recipient + from: keypair.publicKey, // Public key of the sender + amount: '1', // Amount to be sent (in nano MINA) + fee: '1', // Fee to be paid (in nano MINA) + nonce: '0', // Nonce of the sender + }, + keypair.privateKey +); + +const verifiedPayment = client.verifyPayment(payment); +``` + +#### Delegations + +Stake delegations are a way for users to delegate their stake to a validator. This allows the validator to produce blocks on behalf of the delegator. To sign a stake delegation, the following parameters must be provided: + +```js +import Client from 'mina-signer'; +const client = new Client({ network: 'mainnet' }); +const keypair = client.genKeys(); + +const delegation = client.signStakeDelegation( + { + to: keypair.publicKey, // Public key of the validator + from: keypair.publicKey, // Public key of the delegator + fee: '1', // Fee to be paid (in nano MINA) + nonce: '0', // Nonce of the delegator + }, + keypair.privateKey +); + +const verifiedDelegation = client.verifyStakeDelegation(delegation); +``` + +#### Generic Signing + +Mina Signer can take a generic payload for signing and decide which signing method it should use by using `signTransaction()`. +This is useful for applications that want to support both different types of transaction payloads in an easy and maintanable way. + +```js +import Client from 'mina-signer'; +const client = new Client({ network: 'mainnet' }); + +// Sign a payment +client.signTransaction( + { + to: keypair.publicKey, + from: keypair.publicKey, + amount: '1', + fee: '1', + nonce: '0', + }, + keypair.privateKey +); + +// Sign a delegation +client.signTransaction( + { + to: keypair.publicKey, + from: keypair.publicKey, + fee: '1', + nonce: '0', + }, + keypair.privateKey +); + + +// Sign a zkApp transaction +client.signTransaction( + { + zkappCommand: ..., + feePayer: keypair.privateKey + }, + keypair.privateKey +) + +// Sign a simple string payload +client.signTransaction('Hello World', keypair.privateKey); +``` + +#### Rosetta + +If you are developing for [Rosetta](https://www.rosetta-api.org/), Mina Signer lets you take a signed Rosetta transaction and transform it into a Mina compatible transaction that is ready to be broadcasted via the Mina Daemon. + +```js +import Client from 'mina-signer'; +const client = new Client({ network: 'mainnet' }); + +const signedRosettaTx = '...'; +const signedGraphQLCommand = + client.signedRosettaTransactionToSignedCommand(signedRosettaTx); +``` + +### Payment/Delegation Transaction Hashes + +In addition to signing/verifying payments/delegations for the Mina Protocol, Mina Signer allows you to compute the hash that will be used to identify the transaction on the blockchain. This is useful for applications that require the transaction hash before the transaction is broadcasted to the network. + +```js +import Client from 'mina-signer'; +const client = new Client({ network: 'mainnet' }); +const keypair = client.genKeys(); + +const payment = client.signTransaction( + { + to: keypair.publicKey, + from: keypair.publicKey, + amount: '1', + fee: '1', + nonce: '0', + keypair.privateKey +); +const hashedPayment = client.hashPayment(payment); + +const delegation = client.signTransaction( + { + to: keypair.publicKey, + from: keypair.publicKey, + fee: '1', + nonce: '0', + }, + keypair.privateKey +); +const hashedDelegation = client.hashStakeDelegation(delegation); +``` + +## o1js Usage + +### Signing/Verifying zkApp transactions + +### Signing/Verifying Field payloads + +### Nullifiers + +### Examples From 6d44f11603e01968ae54ba9fd374413f25f2df67 Mon Sep 17 00:00:00 2001 From: Martin Minkov Date: Mon, 11 Sep 2023 13:26:56 -0700 Subject: [PATCH 02/12] feat(sidebars.js): add 'zkapps/mina-signer' to the sidebar for better navigation and user experience --- sidebars.js | 1 + 1 file changed, 1 insertion(+) diff --git a/sidebars.js b/sidebars.js index 1fd2081f8..98b048f92 100644 --- a/sidebars.js +++ b/sidebars.js @@ -328,6 +328,7 @@ module.exports = { }, ], }, + 'zkapps/mina-signer', 'zkapps/roadmap', 'zkapps/faq', 'zkapps/zkapps-for-ethereum-developers', From e3c89fbb12d57ca4b4e47bc9d4b0f4a12f9942af Mon Sep 17 00:00:00 2001 From: Martin Minkov Date: Mon, 11 Sep 2023 14:11:37 -0700 Subject: [PATCH 03/12] fix(mina-signer.mdx): correct syntax error by adding missing semicolon feat(mina-signer.mdx): add nonce field to payment object to ensure uniqueness of transactions --- docs/zkapps/mina-signer.mdx | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/zkapps/mina-signer.mdx b/docs/zkapps/mina-signer.mdx index 10fdf1853..8bc19f0eb 100644 --- a/docs/zkapps/mina-signer.mdx +++ b/docs/zkapps/mina-signer.mdx @@ -131,7 +131,7 @@ client.signTransaction( feePayer: keypair.privateKey }, keypair.privateKey -) +); // Sign a simple string payload client.signTransaction('Hello World', keypair.privateKey); @@ -166,6 +166,7 @@ const payment = client.signTransaction( amount: '1', fee: '1', nonce: '0', + }, keypair.privateKey ); const hashedPayment = client.hashPayment(payment); From e2b4c418517e7ba5391be268a9c18352f2ea0fae Mon Sep 17 00:00:00 2001 From: Martin Minkov Date: Tue, 12 Sep 2023 13:49:32 -0700 Subject: [PATCH 04/12] docs(mina-signer.mdx): add detailed usage guide for Mina Signer with o1js This commit adds a comprehensive guide on how to use Mina Signer with o1js for signing and verifying zkApp transactions. It includes a code snippet demonstrating the process and a tip advising when to use Mina Signer over o1js. This update is intended to provide better guidance for developers integrating Mina Signer into their projects. --- docs/zkapps/mina-signer.mdx | 42 +++++++++++++++++++++++++++++++++++++ 1 file changed, 42 insertions(+) diff --git a/docs/zkapps/mina-signer.mdx b/docs/zkapps/mina-signer.mdx index 8bc19f0eb..3e1280cbf 100644 --- a/docs/zkapps/mina-signer.mdx +++ b/docs/zkapps/mina-signer.mdx @@ -185,8 +185,50 @@ const hashedDelegation = client.hashStakeDelegation(delegation); ## o1js Usage +Mina Signer can seamlessly integrate with `o1js`, offering a wide range of features for zkApps. It can be used to sign zkApp transactions, verify zkApp transactions, generate nullifiers, and more. + ### Signing/Verifying zkApp transactions +Mina Signer supports signing and verifying zkApp transactions that have been previously signed with Mina Signer. `o1js` itself can be used to sign zkApp transactions, +but Mina Signer offers the ability to create a transaction that is easily broadcasted via a running Mina Daemon. This can be very useful for wallet applications that want to support zkApps. + +```js +import Client from 'mina-signer'; +import { Mina } from 'o1js'; +const client = new Client({ network: 'testnet' }); +const keypair = client.genKeys(); + +const zkAppTransaction = await Mina.transaction(feePayerAddress, () => { + // ... Interact with a zkApp inside this block to produce a zkApp transaction +}); + +// Sign the zkApp transaction with Mina Signer +const signedZkAppTransaction = client.signZkappCommand( + { + zkappCommand: JSON.parse(JSON.stringify(txn.transaction)), + feePayer: { + feePayer: keypair.publicKey, + fee: '1', + nonce: '0', + memo: 'memo', + }, + }, + keypair.privateKey +); + +// Verify the zkApp transaction with Mina Signer +const verifiedZkAppTransaction = client.verifyZkappCommand( + signedZkAppTransaction +); +``` + +Firstly, when supplying the input parameters for `signZkappCommand()`, we must first parse the zkApp transaction into a string and then into a JSON object. This is because the types generated from `Mina.transaction()` are not compatible with the types used by Mina Signer. +Secondly, we specify the `feePayer` object which contains the public key of the fee payer, the fee to be paid, the nonce of the fee payer, and the memo of the transaction. The `feePayer` object is used to sign the zkApp transaction. + +:::tip +Use `o1js` to sign zkApp transactions if you can, as it's more ergonomic and easier to use. Only use `Mina Signer` if you need to sign zkApp transactions offline and broadcast at a later time (e.g. wallet software). +::: + ### Signing/Verifying Field payloads ### Nullifiers From a7a4c74efd3a9830e8654af5c3facd2067d70c5b Mon Sep 17 00:00:00 2001 From: Martin Minkov Date: Tue, 12 Sep 2023 14:01:13 -0700 Subject: [PATCH 05/12] docs(mina-signer.mdx): add section on signing/verifying Field payloads This commit adds a new section to the Mina Signer documentation explaining how to sign and verify Field payloads. This is useful for developers who want to ensure their payloads have not been tampered with. The section includes code examples and notes on handling Field types from different libraries. --- docs/zkapps/mina-signer.mdx | 26 ++++++++++++++++++++++++++ 1 file changed, 26 insertions(+) diff --git a/docs/zkapps/mina-signer.mdx b/docs/zkapps/mina-signer.mdx index 3e1280cbf..9f530c743 100644 --- a/docs/zkapps/mina-signer.mdx +++ b/docs/zkapps/mina-signer.mdx @@ -231,6 +231,32 @@ Use `o1js` to sign zkApp transactions if you can, as it's more ergonomic and eas ### Signing/Verifying Field payloads +Mina Signer supports signing and verifying Field payloads. This can be helpful if you want to sign a Field payload with a specific keypair and verify the signature as to make sure that it has not been altered by a third party. + +```js +import Client from 'mina-signer'; +const client = new Client({ network: 'testnet' }); +const keypair = client.genKeys(); + +const fields = [10n, 20n, 30n, 340817401n, 2091283n, 1n, 0n]; +const signedFields = client.signFields(fields, keypair.privateKey); +const verifiedFields = client.verifyFields(signedFields); +``` + +If you are using `o1js` to generate Field payloads, you must convert the Fields to BigInts before signing/verifying them. +In Mina Signer, the Field type is a BigInt (while in `o1js` they are a seperate data structure), so you must convert the fields from `o1js` to BigInts before signing/verifying them. + +```js +import Client from 'mina-signer'; +import { Field } from 'o1js'; +const client = new Client({ network: 'testnet' }); +const keypair = client.genKeys(); + +const fields = [Field(10), Field(20)].map((f) => f.toBigInt()); +const signedFields = client.signFields(fields, keypair.privateKey); +const verifiedFields = client.verifyFields(signedFields); +``` + ### Nullifiers ### Examples From 96f22228736893ebd79487c966966ceb7fcb169b Mon Sep 17 00:00:00 2001 From: Martin Minkov Date: Tue, 12 Sep 2023 15:17:55 -0700 Subject: [PATCH 06/12] docs(mina-signer.mdx): add section on nullifiers to provide more comprehensive documentation on zkApp transactions, explaining their purpose and usage with an example code snippet. --- docs/zkapps/mina-signer.mdx | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/docs/zkapps/mina-signer.mdx b/docs/zkapps/mina-signer.mdx index 9f530c743..a279ff731 100644 --- a/docs/zkapps/mina-signer.mdx +++ b/docs/zkapps/mina-signer.mdx @@ -259,4 +259,18 @@ const verifiedFields = client.verifyFields(signedFields); ### Nullifiers +Mina Signer supports generating nullifiers for zkApp transactions. In the realm of cryptographic mechanisms, nullifiers serve as a unique identifier, safeguarding anonymity while ensuring account integrity and preventing illicit activities such as double-spending. +They work by publicly committing to an anonymous account, permitting consistent identity establishment for covert actions. + +To create a nullifier, specify a message and the private key of the sender. The message must be an array of BigInts. + +```js +import Client from 'mina-signer'; +const client = new Client({ network: 'testnet' }); +const keypair = client.genKeys(); + +const message = [10n, 20n, 30n, 340817401n, 2091283n, 1n, 0n]; +const nullifier = client.createNullifier(message, keypair.privateKey); +``` + ### Examples From 54a56450c597bf40d294d4e631f5f31ef1a8a350 Mon Sep 17 00:00:00 2001 From: Martin Minkov Date: Tue, 12 Sep 2023 15:19:21 -0700 Subject: [PATCH 07/12] fix(mina-signer.mdx): remove invalid fee payer param --- docs/zkapps/mina-signer.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/zkapps/mina-signer.mdx b/docs/zkapps/mina-signer.mdx index a279ff731..e9fbf5610 100644 --- a/docs/zkapps/mina-signer.mdx +++ b/docs/zkapps/mina-signer.mdx @@ -128,7 +128,7 @@ client.signTransaction( client.signTransaction( { zkappCommand: ..., - feePayer: keypair.privateKey + feePayer: ... }, keypair.privateKey ); From 395864a49a9377105426f9299afef62a4a122285 Mon Sep 17 00:00:00 2001 From: Martin Minkov Date: Tue, 12 Sep 2023 15:24:04 -0700 Subject: [PATCH 08/12] docs(mina-signer.mdx): improve clarity and specificity in documentation 1. Specify that the installation command is for Mina Signer for better context. 2. Remove the definite article before Mina Signer for consistency. 3. Add explanation for the need to specify the network during Mina Signer initialization. 4. Move the default network information to a tip box for better visibility. 5. Specify that Mina Signer supports signing and verifying of arbitrary Field payloads for better understanding. --- docs/zkapps/mina-signer.mdx | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/docs/zkapps/mina-signer.mdx b/docs/zkapps/mina-signer.mdx index e9fbf5610..859c4357a 100644 --- a/docs/zkapps/mina-signer.mdx +++ b/docs/zkapps/mina-signer.mdx @@ -8,7 +8,7 @@ Mina Signer is a NodeJS/Browser compatible JavaScript library built for the Mina ## Installation -To install the library, run the following command: +To install the Mina Signer, run the following command: ```sh npm install mina-signer @@ -16,13 +16,15 @@ npm install mina-signer ## Mina Protocol Usage -The Mina Signer offers a wide range of features for the Mina Protocol. It can be used to generate keys, sign transactions, verify transactions, and more. Mina Signer also supports compatability between different networks, such as mainnet and testnet. +Mina Signer offers a wide range of features for the Mina Protocol. It can be used to generate keys, sign transactions, verify transactions, and more. Mina Signer also supports compatability between different networks, such as mainnet and testnet. ### Specifying the network -When initializing the Mina Signer, the network must be specified. This is done by passing the `network` parameter to the constructor. The network can be either `mainnet` or `testnet`. If no network is specified, the default network is `mainnet`. +When initializing Mina Signer, the network must be specified. This is because different networks can potentially be using different crytographic methods. +This is done by passing the `network` parameter to the constructor. The network can be either `mainnet` or `testnet`. :::tip +If no network is specified, the default network is `mainnet`. If you wish to specify the current Berkeley network, the value of `testnet` should be used ::: @@ -231,7 +233,7 @@ Use `o1js` to sign zkApp transactions if you can, as it's more ergonomic and eas ### Signing/Verifying Field payloads -Mina Signer supports signing and verifying Field payloads. This can be helpful if you want to sign a Field payload with a specific keypair and verify the signature as to make sure that it has not been altered by a third party. +Mina Signer supports signing and verifying Field arbitrary payloads. This can be helpful if you want to sign a Field payload with a specific keypair and verify the signature as to make sure that it has not been altered by a third party. ```js import Client from 'mina-signer'; From d0a9a12000d53ccfea3d2357ac17bb4ddbae9222 Mon Sep 17 00:00:00 2001 From: Martin Minkov Date: Tue, 12 Sep 2023 15:31:50 -0700 Subject: [PATCH 09/12] docs(mina-signer.mdx): update terminology and add more context to improve clarity 1. Replace 'keys' with 'keypairs' for more accurate terminology. 2. Add information about broadcasting signed payments or delegations to the network via the Mina Daemon. 3. Add hyperlink to 'o1js' for better navigation and understanding. 4. Modify description of Mina Signer's integration with 'o1js' to include signing/verifying Field payloads. 5. Clarify that Mina Signer can sign a zkApp transaction that can easily be broadcasted with a Mina Daemon. 6. Remove 'Examples' section as it seems to be empty and unnecessary. --- docs/zkapps/mina-signer.mdx | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) diff --git a/docs/zkapps/mina-signer.mdx b/docs/zkapps/mina-signer.mdx index 859c4357a..585cf58f8 100644 --- a/docs/zkapps/mina-signer.mdx +++ b/docs/zkapps/mina-signer.mdx @@ -36,7 +36,7 @@ const TestnetClient = new Client({ network: 'testnet' }); // Specify testnet (Be ### Generating keys -With Mina Signer, generating keys is straightforward. +With Mina Signer, generating keypairs is straightforward. ```js import Client from 'mina-signer'; @@ -47,6 +47,7 @@ const keypair = client.genKeys(); // Generates a public and private keypair ### Signing/Verifying transactions The Mina Signer supports signing and verifying both transactions and stake delegations. To sign a transaction or delegation, the private key of the sender must be provided. To verify a transaction or delegation, the public key of the sender must be provided. +Once the payment or delegation is signed, it can be broadcasted to the network via the Mina Daemon. #### Payments @@ -101,6 +102,7 @@ This is useful for applications that want to support both different types of tra ```js import Client from 'mina-signer'; const client = new Client({ network: 'mainnet' }); +const keypair = client.genKeys(); // Sign a payment client.signTransaction( @@ -187,16 +189,17 @@ const hashedDelegation = client.hashStakeDelegation(delegation); ## o1js Usage -Mina Signer can seamlessly integrate with `o1js`, offering a wide range of features for zkApps. It can be used to sign zkApp transactions, verify zkApp transactions, generate nullifiers, and more. +Mina Signer can seamlessly integrate with [o1js](/zkapps/o1js), offering a wide range of features for zkApps. It can be used to sign/verify zkApp transactions, sign/verify Field payloads, sign generate nullifiers, and more. ### Signing/Verifying zkApp transactions -Mina Signer supports signing and verifying zkApp transactions that have been previously signed with Mina Signer. `o1js` itself can be used to sign zkApp transactions, -but Mina Signer offers the ability to create a transaction that is easily broadcasted via a running Mina Daemon. This can be very useful for wallet applications that want to support zkApps. +Mina Signer supports signing and verifying zkApp transactions. `o1js` itself can be used to sign zkApp transactions, +but Mina Signer offers the ability to sign a zkApp transaction that can easily be broadcasted with a Mina Daemon. This can be very useful for wallet applications that want to support zkApps. ```js import Client from 'mina-signer'; import { Mina } from 'o1js'; + const client = new Client({ network: 'testnet' }); const keypair = client.genKeys(); @@ -274,5 +277,3 @@ const keypair = client.genKeys(); const message = [10n, 20n, 30n, 340817401n, 2091283n, 1n, 0n]; const nullifier = client.createNullifier(message, keypair.privateKey); ``` - -### Examples From dcdb87082350fb6c8d56d0d1cb979e9cd023f108 Mon Sep 17 00:00:00 2001 From: Martin Minkov Date: Tue, 12 Sep 2023 15:33:59 -0700 Subject: [PATCH 10/12] docs(mina-signer.mdx): update description field from 'TODO' to a brief summary of the Mina Signer library to provide a clear and concise overview of the library's purpose and functionality --- docs/zkapps/mina-signer.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/zkapps/mina-signer.mdx b/docs/zkapps/mina-signer.mdx index 585cf58f8..399be41f8 100644 --- a/docs/zkapps/mina-signer.mdx +++ b/docs/zkapps/mina-signer.mdx @@ -1,7 +1,7 @@ --- id: mina-signer title: Mina Signer -description: TODO +description: A NodeJS/Browser-compatible JavaScript library for the Mina Protocol --- Mina Signer is a NodeJS/Browser compatible JavaScript library built for the Mina Protocol. It empowers developers to sign transactions and generate keys seamlessly. One of its standout features is its capability to sign transactions offline, which can then be broadcasted to the network as and when needed. There are additional features such as signing zkApp transactions, verifying zkApp transactions, generating nullifiers, and more. From 8a92a1d7c7757379ba61a3c24e43a2cace2513f7 Mon Sep 17 00:00:00 2001 From: Martin Minkov Date: Tue, 12 Sep 2023 15:41:02 -0700 Subject: [PATCH 11/12] docs(mina-signer.mdx): improve readability and clarity of the documentation - Reworded several sentences for better readability and clarity. - Organized the features of Mina Signer into a list for easier understanding. - Made the instructions for specifying the network more explicit. - Changed the headers to use '&' instead of '/' for consistency. - Expanded on the explanation of nullifiers for better understanding. - Made the instructions for generating a nullifier more explicit. --- docs/zkapps/mina-signer.mdx | 51 ++++++++++++++++++++++--------------- 1 file changed, 30 insertions(+), 21 deletions(-) diff --git a/docs/zkapps/mina-signer.mdx b/docs/zkapps/mina-signer.mdx index 399be41f8..13e81cd9e 100644 --- a/docs/zkapps/mina-signer.mdx +++ b/docs/zkapps/mina-signer.mdx @@ -4,11 +4,11 @@ title: Mina Signer description: A NodeJS/Browser-compatible JavaScript library for the Mina Protocol --- -Mina Signer is a NodeJS/Browser compatible JavaScript library built for the Mina Protocol. It empowers developers to sign transactions and generate keys seamlessly. One of its standout features is its capability to sign transactions offline, which can then be broadcasted to the network as and when needed. There are additional features such as signing zkApp transactions, verifying zkApp transactions, generating nullifiers, and more. +Mina Signer is a NodeJS/Browser compatible JavaScript library tailored for the Mina Protocol. This library aids developers in seamlessly signing transactions and generating keys. A noteworthy feature is the ability to sign transactions offline, allowing for their broadcasting to the network whenever required. It also supports functionalities such as signing zkApp transactions, verifying these transactions, generating nullifiers, and more. ## Installation -To install the Mina Signer, run the following command: +To incorporate Mina Signer into your project: ```sh npm install mina-signer @@ -16,16 +16,22 @@ npm install mina-signer ## Mina Protocol Usage -Mina Signer offers a wide range of features for the Mina Protocol. It can be used to generate keys, sign transactions, verify transactions, and more. Mina Signer also supports compatability between different networks, such as mainnet and testnet. +Mina Signer offers a wide range of features for the Mina Protocol: + +- Generate keys +- Sign transactions +- Verify transactions + +Additionally, it ensures compatibility across various networks, like mainnet and testnet. ### Specifying the network -When initializing Mina Signer, the network must be specified. This is because different networks can potentially be using different crytographic methods. -This is done by passing the `network` parameter to the constructor. The network can be either `mainnet` or `testnet`. +When importing and initializing Mina Signer, it's imperative to designate the desired network. +Different networks may employ varying cryptographic methods. This specification is executed by supplying the network parameter during the constructor's invocation. +Possible values are `mainnet` and `testnet`. :::tip -If no network is specified, the default network is `mainnet`. -If you wish to specify the current Berkeley network, the value of `testnet` should be used +By default, if no network is explicitly chosen, `mainnet` is the default choice. For the Berkeley network, use `testnet`. ::: ```js @@ -44,10 +50,10 @@ const client = new Client({ network: 'mainnet' }); // Specify mainnet const keypair = client.genKeys(); // Generates a public and private keypair ``` -### Signing/Verifying transactions +### Signing & Verifying Transactions -The Mina Signer supports signing and verifying both transactions and stake delegations. To sign a transaction or delegation, the private key of the sender must be provided. To verify a transaction or delegation, the public key of the sender must be provided. -Once the payment or delegation is signed, it can be broadcasted to the network via the Mina Daemon. +Mina Signer facilitates both transaction and stake delegation signing and verification. To sign a transaction, the sender's private must be provided. +Conversely, for verification, the sender's public key must be provided. Post-signing, the Mina Daemon can be utilized to broadcast the payment or delegation. #### Payments @@ -96,8 +102,8 @@ const verifiedDelegation = client.verifyStakeDelegation(delegation); #### Generic Signing -Mina Signer can take a generic payload for signing and decide which signing method it should use by using `signTransaction()`. -This is useful for applications that want to support both different types of transaction payloads in an easy and maintanable way. +Mina Signer can accept a generic payload and determine the most apt signing approach via `signTransaction()`. +This functionality is especially beneficial for applications that support different types of transactions. ```js import Client from 'mina-signer'; @@ -143,7 +149,7 @@ client.signTransaction('Hello World', keypair.privateKey); #### Rosetta -If you are developing for [Rosetta](https://www.rosetta-api.org/), Mina Signer lets you take a signed Rosetta transaction and transform it into a Mina compatible transaction that is ready to be broadcasted via the Mina Daemon. +For those developing with [Rosetta](https://www.rosetta-api.org/), Mina Signer provides an avenue to transform a signed Rosetta transaction into a Mina-compliant transaction, ready for broadcasting through the Mina Daemon. ```js import Client from 'mina-signer'; @@ -154,7 +160,7 @@ const signedGraphQLCommand = client.signedRosettaTransactionToSignedCommand(signedRosettaTx); ``` -### Payment/Delegation Transaction Hashes +### Payment & Delegation Transaction Hashes In addition to signing/verifying payments/delegations for the Mina Protocol, Mina Signer allows you to compute the hash that will be used to identify the transaction on the blockchain. This is useful for applications that require the transaction hash before the transaction is broadcasted to the network. @@ -189,9 +195,13 @@ const hashedDelegation = client.hashStakeDelegation(delegation); ## o1js Usage -Mina Signer can seamlessly integrate with [o1js](/zkapps/o1js), offering a wide range of features for zkApps. It can be used to sign/verify zkApp transactions, sign/verify Field payloads, sign generate nullifiers, and more. +Mina Signer can seamlessly integrate with [o1js](/zkapps/o1js),delivering an array of features for zkApps like: -### Signing/Verifying zkApp transactions +- zkApp transaction signing and verification +- Field payload signing and verification +- Nullifier generation + +### Signing & Verifying zkApp transactions Mina Signer supports signing and verifying zkApp transactions. `o1js` itself can be used to sign zkApp transactions, but Mina Signer offers the ability to sign a zkApp transaction that can easily be broadcasted with a Mina Daemon. This can be very useful for wallet applications that want to support zkApps. @@ -236,7 +246,7 @@ Use `o1js` to sign zkApp transactions if you can, as it's more ergonomic and eas ### Signing/Verifying Field payloads -Mina Signer supports signing and verifying Field arbitrary payloads. This can be helpful if you want to sign a Field payload with a specific keypair and verify the signature as to make sure that it has not been altered by a third party. +Mina Signer can sign and validate Field payloads. This is invaluable when ensuring a Field payload's authenticity, as it confirms the payload remains untampered by external parties. ```js import Client from 'mina-signer'; @@ -264,10 +274,9 @@ const verifiedFields = client.verifyFields(signedFields); ### Nullifiers -Mina Signer supports generating nullifiers for zkApp transactions. In the realm of cryptographic mechanisms, nullifiers serve as a unique identifier, safeguarding anonymity while ensuring account integrity and preventing illicit activities such as double-spending. -They work by publicly committing to an anonymous account, permitting consistent identity establishment for covert actions. - -To create a nullifier, specify a message and the private key of the sender. The message must be an array of BigInts. +Mina Signer supports generating nullifiers for zkApp transactions. In the world of cryptography, nullifiers play a pivotal role. +They stand as unique markers, maintaining anonymity yet ensuring account reliability, and staving off illicit undertakings like double-spends. +To generate a nullifier, provide a message (an array of BigInts) and the sender's private key. ```js import Client from 'mina-signer'; From 502be72d20eeabf2b76f086607a2c8e38fc4af18 Mon Sep 17 00:00:00 2001 From: Martin Minkov Date: Wed, 13 Sep 2023 14:17:51 -0700 Subject: [PATCH 12/12] docs(mina-signer.mdx): remove backticks from o1js for consistency and readability The backticks were removed from o1js to maintain consistency throughout the document and improve readability. The backticks are typically used for code snippets or commands, not for naming libraries or tools. --- docs/zkapps/mina-signer.mdx | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/zkapps/mina-signer.mdx b/docs/zkapps/mina-signer.mdx index 13e81cd9e..6deff7a6c 100644 --- a/docs/zkapps/mina-signer.mdx +++ b/docs/zkapps/mina-signer.mdx @@ -203,7 +203,7 @@ Mina Signer can seamlessly integrate with [o1js](/zkapps/o1js),delivering an arr ### Signing & Verifying zkApp transactions -Mina Signer supports signing and verifying zkApp transactions. `o1js` itself can be used to sign zkApp transactions, +Mina Signer supports signing and verifying zkApp transactions. o1js itself can be used to sign zkApp transactions, but Mina Signer offers the ability to sign a zkApp transaction that can easily be broadcasted with a Mina Daemon. This can be very useful for wallet applications that want to support zkApps. ```js @@ -241,7 +241,7 @@ Firstly, when supplying the input parameters for `signZkappCommand()`, we must f Secondly, we specify the `feePayer` object which contains the public key of the fee payer, the fee to be paid, the nonce of the fee payer, and the memo of the transaction. The `feePayer` object is used to sign the zkApp transaction. :::tip -Use `o1js` to sign zkApp transactions if you can, as it's more ergonomic and easier to use. Only use `Mina Signer` if you need to sign zkApp transactions offline and broadcast at a later time (e.g. wallet software). +Use o1js to sign zkApp transactions if you can, as it's more ergonomic and easier to use. Only use `Mina Signer` if you need to sign zkApp transactions offline and broadcast at a later time (e.g. wallet software). ::: ### Signing/Verifying Field payloads @@ -258,8 +258,8 @@ const signedFields = client.signFields(fields, keypair.privateKey); const verifiedFields = client.verifyFields(signedFields); ``` -If you are using `o1js` to generate Field payloads, you must convert the Fields to BigInts before signing/verifying them. -In Mina Signer, the Field type is a BigInt (while in `o1js` they are a seperate data structure), so you must convert the fields from `o1js` to BigInts before signing/verifying them. +If you are using o1js to generate Field payloads, you must convert the Fields to BigInts before signing/verifying them. +In Mina Signer, the Field type is a BigInt (while in o1js they are a seperate data structure), so you must convert the fields from o1js to BigInts before signing/verifying them. ```js import Client from 'mina-signer';