From 13d525af51ef7104cae58c7d0f68b0895fd95ea5 Mon Sep 17 00:00:00 2001
From: Shigoto-dev19 <shigoto-dev19@protonmail.com>
Date: Mon, 6 May 2024 13:56:36 +0100
Subject: [PATCH] Update README

---
 README.md | 78 +++++++++++++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 76 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index ae7050c..1a508d8 100644
--- a/README.md
+++ b/README.md
@@ -1,6 +1,51 @@
-# Mina zkApp: Base64 O1js
+# O1JS Base64 Decode
 
-This template uses TypeScript.
+This repository offers a straightforward way to decode base64-encoded input bytes. It's designed to be easy to use and reliable tool for decoding base64 data in various projects using [o1js](https://docs.minaprotocol.com/zkapps/o1js/).
+
+## How to use the package
+
+1. Install the package
+
+```sh
+npm install o1js-base64
+```
+
+2. Import the `base64Decode` function
+
+```typescript
+import { base64Decode } from 'o1js-base64';
+```
+
+3. Import the provable type `Bytes` from `o1js`
+
+```typescript
+import { Bytes } from 'o1js';
+```
+
+4. For the example of a **string** input:
+
+```typescript
+const encodedB64 = Bytes.fromString('7xQM+vU=');
+const decodedB64 = base64Decode(encodedB64, 5);
+```
+
+### Notes
+
+- The `base64Decode` function will throw an error if the `encodedB64` length is not a multiple of 4 or contains **non-base64** characters.
+
+- Ensure to provide the accurate **decoded byte length** parameter when invoking the `base64Decode` function.
+
+- Utilize the `calculateB64DecodedBytesLength` function available within the package.
+
+  - You can find an example of its usage in this [code snippet](https://github.com/Shigoto-dev19/o1js-base64/blob/main/src/base64.test.ts#L10-L17).
+
+  - If needed, you can refer to this [gist](https://gist.github.com/carlos-jenkins/3d28f9b05b5ae679ae5efe13d9cff9e8) for manual calculation guidance.
+
+- When employing the `base64Decode` function within a **zkProgram** or **zkApp**, it's crucial to use the appropriate `provable Byte` types for both input and output.
+
+  - For reference, consider this [snippet](https://github.com/Shigoto-dev19/o1js-base64/blob/main/src/run.ts#L7-L20), which demonstrates a zkProgram designed to decode a base64-encoded SHA256 digest.
+  - The encoded input has a length of 44, while the expected decoded output is 32 bytes long.
+  - Therefore, ensure the provable Byte types are accurately and deterministically assigned to match the input and output lengths.
 
 ## How to build
 
@@ -21,6 +66,35 @@ npm run testw # watch mode
 npm run coverage
 ```
 
+## How to benchmark
+
+```sh
+npm run benchmark
+```
+
+### Preview
+
+| Summary         |      |
+| --------------- | ---- |
+| Total rows      | 8081 |
+| Generic         | 1921 |
+| EndoMulScalar   | 88   |
+| RangeCheck0     | 2112 |
+| RangeCheck1     | 1056 |
+| Zero            | 1848 |
+| ForeignFieldAdd | 1056 |
+
+| Action  | Time (s) |
+| ------- | -------- |
+| Compile | 1.985    |
+| Prove   | 15.496   |
+| Verify  | 1.021    |
+
+## Acknowledgement
+
+This repo is inspired by the [circom base64](https://github.com/zkemail/zk-email-verify/blob/main/packages/circuits/lib/base64.circom)
+implementation.
+
 ## License
 
 [Apache-2.0](LICENSE)