@verified-network/verified-custody 0.3.6 → 0.3.7

package/README.md

@@ -1,16 +1,27 @@
-# Verified Custody
+## 🛡️ Verified Custody
 
-Verified Custody is a react submodule for Custody of digital assets. This react module allows users to create blockchain wallets where private keys are sharded and stored on the blockchain itself in encrypted form. Users do not have to remember mnemonics or back up private keys. Verified Custody requires co-signers to be added by a wallet user and co-signers can be requested to re-generate the sharded and stored keys. 
+**Verified Custody** is a React submodule designed for custody of digital assets. This React module enables users to create blockchain wallets where private keys are sharded and stored on-chain in encrypted form. Users **do not need to remember mnemonics or back up private keys**.
 
-### Installation:
+Verified Custody requires wallet users to add co-signers, who can be requested to re-generate the sharded and stored keys, adding additional security and recovery options.
 
-```
+## Objectives
+
+- Provide an easy-to-integrate React module for digital asset custody.
+- Support user onboarding (FTU) and returning user workflows.
+- Enable secure co-signer management and transaction signing.
+- Allow flexible communication with co-signers via customizable helper functions.
+- Support wallet recovery and transaction signing workflows.
+
+# ⚙️ Installation
+
+```bash
 npm install @verified-network/verified-custody
 ```
 
+# 💻 Usage Example
+
 ```jsx
 import React from "react";
-
 import { VerifiedCustody } from "@verified-network/verified-custody";
 
 function App() {
@@ -22,46 +33,58 @@ function App() {
 }
 ```
 
-### Build:
+# 🛠️ Build
+
+This module is built with TypeScript and works for both JavaScript and TypeScript React/Vite projects.
+All components are compiled and available under the dist/ directory.
+The module exports React components and helper functions useful for changing UI based on user state or custom business logic.
+
+## 🔄 Main Components & Workflows
+
+The complete custody workflow component that handles new and existing users through multiple steps.
+
+```jsx
+<VerifiedCustody />
+```
+
+# 🆕 First Time Users (FTU)
+
+`<FTUPage />` Full workflow for first-time users, consisting of:
 
-- This module is built with typescript and work for both javascript and typescript react/vite projects.
-- All the components of the module is compiled and available under the dist/ directory.
+    <ContactPage /> Starting point where users enter phone number or email to receive an OTP (One-Time Password).
 
-The react module exports react components and helper functions which will be useful when changing UI based on a user's state or any business logic
+    <OTPPage />  Where new and existing users verify or resend OTP.
 
-\***\*< VerifiedCustody />\*\*** component is the completed workflow of the custody module, it handles full workflow for new and existing users in steps; it consists of:
+    <CreatePinPage />  Users either:
 
-# First Time Users
+    Create a 4-digit PIN to secure their account.
 
-\***\*< FTUPage />\*\*** component which handles full workflow for First Time Users. This consists of:
+    Input their existing PIN and get redirected accordingly.
 
-\***\*< ContactPage />\*\*** component which is the starting point for all users, where they are required to input their phone number or email. And they receive an OTP(one time password).
+    Reset/Update their existing PIN to change to a new PIN.
 
-\***\*< OTPPage />\*\*** component which is where new/existing users verify and resend OTP.
+    New user accounts are created here after verifying phone/email.
 
-\***\*< CreatePinPage />\*\*** component which is where all users either;
+    <AddCoSignersPage /> New users add co-signers and define signing rules:
+    Up to 5 co-signers can be added with a minimum of 2 required signers.
 
-1.  create 4 digit pin to secure their account.
-2.  Input their existing pin and get redirected to another page.
-    In this component new users accounts are created as they had verified their Phone number/Email from previous components.
+# 🔄 Returning Users
 
-\***\*< AddCoSignersPage />\*\*** component which is where all new users gets to add coSigners to their account and decide the rule of signing. Users can add up to 5 Co-signers with 2 as minimum required signers.
+`<EnterPinPage />` Existing users enter their PIN to:
 
-# Returning Users
+    Connect wallet/account to an application.
 
-\***\*< EnterPinPage />\*\*** component which is where existing/returning users gets to input their account pin to perform various actions like;
+    Accept or reject co-signer invitations.
 
-1.  connect their account/wallet to an application.
-2.  Accept/Reject Co-signers invitation.
-3.  Recover their lost account/wallet keys
-4.  Sign account recovery transaction for users
-5.  Sign regular transactions. e.t.c
+    Recover lost account/wallet keys.
 
-## Usage:
+    Sign account recovery transactions.
 
-Note: To implement this module in your project there are some important component props required.
+    Sign regular transactions, etc.
 
-# Components Props Type:
+## 📋 Usage Details & Component Props
+
+# Component Props Types
 
 ```jsx
 export interface VerifiedCustodyProps {
@@ -83,7 +106,8 @@ export type VerifiedWalletAction =
   | "getPk"
   | "invitation"
   | "signRecovery"
-  | "completeRecovery";
+  | "completeRecovery"
+  | "eth_sendTransaction";
 
 export type VerifiedWalletVault = {
   vaultId: string,
@@ -151,287 +175,185 @@ export interface VerifiedCustodyHelpers {
 }
 ```
 
-1. action: which can be either "connect_wallet" or "getPk" or "invitation" or "signRecovery" or "completeRecovery". if action is not passed in the props it will create account for new users or login for an existing users.
-2. helperFunctions:
-   For Example: sendCoSignerInvitation: this is required to send messages to cosigners using their email or phone number. it must take 4 parameters: ` jsx 
-channel: "sms" | "email",
-cosigerId: string, //email or phone number of the cosigner added. note: phone number must be ``+${countryPhoneCode}${10DigitsPhoneNumber} `` for example: +10987654321 where 1 is the countryCode and 0987654321 is the phone number.
-cretorId: string, //email or phone number of the account creator. note: phone number must be ``+${countryPhoneCode}${10DigitsPhoneNumber} `` for example: +10987654321 where 1 is the countryCode and 0987654321 is the phone number.
-hashedCretorPin: string  `
-   and return `true or false` true when message sends without error and false incase of any error.
+# Prop Descriptions
+
+    action:
+    Optional. Can be one of:
+    "connect_wallet" | "getPk" | "invitation" | "signRecovery" | "completeRecovery" | "eth_sendTransaction"
+    If omitted, the component handles account creation or login for new/existing users.
 
-Check the code Below for better explaination of how all helper functions work.
+    helperFunctions:
+    An object containing functions that handle messaging and notifications (email/SMS) for co-signers and creators.
+
+    Example:
+    sendCoSignerInvitation must take four parameters:
+    channel: "sms" | "email"
+    cosigerId: string (email or phone number of the co-signer)
+    phone number must be in format +{countryCode}{10DigitNumber} e.g. +1098765432
+    cretorId: string (email or phone number of the wallet creator)
+    hashedCretorPin: string
+    It returns a Promise resolving to true on successful message delivery, otherwise false.
 
-### Full workflow with one component(handle First time users, existing user and all type of actions)
+# 🚀 Full Workflow Example
 
 ```jsx
-import React from 'react';
-
-import { VerifiedCustody} from '@verified-network/verified-custody';
-
-function App(){
-
-const myCustomSendCoSignerInvitation = async(
- channel: "sms" | "email",
- cosigerId: string,
- cretorId: string,
- hashedCretorPin: string
- ) => Promise<boolean> {
-     try {
-       //sends email/messages depending on the channel
-       if(channel === "sms") {
-         //send message to cosigerId phone number using creatorId and hashedCretorPin in message
-         return true
-       }else if(channel === "email") {
-         //send message to cosigerId email using creatorId and hashedCretorPin in message
-         return true
-       }else {
-         return false
-       }
-     }catch(err) {
-       //handles error
-       return false
-     }
- }
-
- const myCustomSendCreatorConfirmation = async(
-   channel: "sms" | "email",
-   cretorId: string,
-   cosigersList: [],
-   requiredSigners: number
- ) => Promise<boolean> {
-     try {
-       //sends email/messages depending on the channel
-       if(channel === "sms") {
-         //send message to cretorId phone number  showing creator his coSigners list and rule of signer using requiredSigners and totalNumber of coSignersList
-         return true
-       }else if(channel === "email") {
-          //send message to cretorId email showing creator his coSigners list and rule of signer using requiredSigners and totalNumber of coSignersList
-         return true
-       }else {
-         return false
-       }
-     }catch(err) {
-       //handles error
-       return false
-     }
- }
-
-// no action/ create account for new user or login existing user.
- return (
-   <div>
-     <VerifiedCustody helperFunctions={
-       sendCoSignerInvitation: myCustomSendCoSignerInvitation,
-       sendCreatorConfirmation: myCustomSendCreatorConfirmation,
-       sendCreatorInitiation: myCustomsendCreatorInitiation,
-       sendCreatorSigned: myCustomSendCreatorSigned,
-       sendCreatorCompleted: myCustomSendCreatorCompleted,
-       sendCreatorAcceptance: myCustomSendCreatorAcceptance,
-       sendCreatorRejection: myCustomSendCreatorRejection
-     } />
-   </div>
- );
-
- // connect existing user account
- return (
-   <div>
-     <VerifiedCustody action="connect_wallet" actionText="CustomActionTextToDisplay like: Connect Your Account" origin="websiteToConnectToUrl" title="websiteToConnectToTitle" helperFunctions={
-       sendCoSignerInvitation: myCustomSendCoSignerInvitation,
-       sendCreatorConfirmation: myCustomSendCreatorConfirmation,
-       sendCreatorInitiation: myCustomsendCreatorInitiation,
-       sendCreatorSigned: myCustomSendCreatorSigned,
-       sendCreatorCompleted: myCustomSendCreatorCompleted,
-       sendCreatorAcceptance: myCustomSendCreatorAcceptance,
-       sendCreatorRejection: myCustomSendCreatorRejection
-     } />
-   </div>
- );
-
- //accept or reject coSigner invitation
- return (
-   <div>
-     <VerifiedCustody action="invitation" origin="websiteUrl" title="websiteTitle" helperFunctions={
-       sendCoSignerInvitation: myCustomSendCoSignerInvitation,
-       sendCreatorConfirmation: myCustomSendCreatorConfirmation,
-       sendCreatorInitiation: myCustomsendCreatorInitiation,
-       sendCreatorSigned: myCustomSendCreatorSigned,
-       sendCreatorCompleted: myCustomSendCreatorCompleted,
-       sendCreatorAcceptance: myCustomSendCreatorAcceptance,
-       sendCreatorRejection: myCustomSendCreatorRejection
-     } />
-   </div>
- );
-
- //sign account recovery for an existing account as their cosigner
- return (
-   <div>
-     <VerifiedCustody action="signRecovery" origin="websiteUrl" title="websiteTitle" helperFunctions={
-       sendCoSignerInvitation: myCustomSendCoSignerInvitation,
-       sendCreatorConfirmation: myCustomSendCreatorConfirmation,
-       sendCreatorInitiation: myCustomsendCreatorInitiation,
-       sendCreatorSigned: myCustomSendCreatorSigned,
-       sendCreatorCompleted: myCustomSendCreatorCompleted,
-       sendCreatorAcceptance: myCustomSendCreatorAcceptance,
-       sendCreatorRejection: myCustomSendCreatorRejection
-     } />
-   </div>
- );
-
- //complete account recovery for an existing account
- return (
-   <div>
-     <VerifiedCustody action="completeRecovery" origin="websiteUrl" title="websiteTitle" helperFunctions={
-       sendCoSignerInvitation: myCustomSendCoSignerInvitation,
-       sendCreatorConfirmation: myCustomSendCreatorConfirmation,
-       sendCreatorInitiation: myCustomsendCreatorInitiation,
-       sendCreatorSigned: myCustomSendCreatorSigned,
-       sendCreatorCompleted: myCustomSendCreatorCompleted,
-       sendCreatorAcceptance: myCustomSendCreatorAcceptance,
-       sendCreatorRejection: myCustomSendCreatorRejection
-     } />
-   </div>
- );
+import React from "react";
+import { VerifiedCustody } from "@verified-network/verified-custody";
+
+function App() {
+  const myCustomSendCoSignerInvitation = async (
+    channel: "sms" | "email",
+    cosigerId: string,
+    cretorId: string,
+    hashedCretorPin: string
+  ): Promise<boolean> => {
+    try {
+      if (channel === "sms") {
+        // send SMS to cosigerId with cretorId and hashedCretorPin
+        return true;
+      } else if (channel === "email") {
+        // send email to cosigerId with cretorId and hashedCretorPin
+        return true;
+      }
+      return false;
+    } catch (err) {
+      return false;
+    }
+  };
+
+  const myCustomSendCreatorConfirmation = async (
+    channel: "sms" | "email",
+    cretorId: string,
+    cosigersList: [],
+    requiredSigners: number
+  ): Promise<boolean> => {
+    try {
+      if (channel === "sms") {
+        // send SMS showing coSigners and signing rules to cretorId
+        return true;
+      } else if (channel === "email") {
+        // send email showing coSigners and signing rules to cretorId
+        return true;
+      }
+      return false;
+    } catch (err) {
+      // If reverted for any reason return false
+      return false;
+    }
+  };
+
+  // Similarly define other helper functions: myCustomsendCreatorInitiation, myCustomSendCreatorSigned, etc.
+
+  return (
+    <div>
+      <VerifiedCustody
+        helperFunctions={{
+          sendCoSignerInvitation: myCustomSendCoSignerInvitation,
+          sendCreatorConfirmation: myCustomSendCreatorConfirmation,
+          sendCreatorInitiation: myCustomsendCreatorInitiation,
+          sendCreatorSigned: myCustomSendCreatorSigned,
+          sendCreatorCompleted: myCustomSendCreatorCompleted,
+          sendCreatorAcceptance: myCustomSendCreatorAcceptance,
+          sendCreatorRejection: myCustomSendCreatorRejection,
+        }}
+      />
+    </div>
+  );
+
+  // You can also set action prop for different user flows, e.g. action="connect_wallet"
 }
 ```
 
-### First time users
+# 🆕 First Time Users
 
 ```jsx
-import React from 'react';
-
-import { FTUPage} from '@verified-network/verified-custody';
-
-function App(){
-
-const myCustomSendCoSignerInvitation = async(
- channel: "sms" | "email",
- cosigerId: string,
- cretorId: string,
- hashedCretorPin: string
- ) => Promise<boolean> {
-     try {
-       //sends email/messages depending on the channel
-       if(channel === "sms") {
-         //send message to cosigerId phone number using creatorId and hashedCretorPin in message
-         return true
-       }else if(channel === "email") {
-         //send message to cosigerId email using creatorId and hashedCretorPin in message
-         return true
-       }else {
-         return false
-       }
-     }catch(err) {
-       //handles error
-       return false
-     }
- }
-
- const myCustomSendCreatorConfirmation = async(
-   channel: "sms" | "email",
-   cretorId: string,
-   cosigersList: [],
-   requiredSigners: number
- ) => Promise<boolean> {
-     try {
-       //sends email/messages depending on the channel
-       if(channel === "sms") {
-         //send message to cretorId phone number  showing creator his coSigners list and rule of signer using requiredSigners and totalNumber of coSignersList
-         return true
-       }else if(channel === "email") {
-          //send message to cretorId email showing creator his coSigners list and rule of signer using requiredSigners and totalNumber of coSignersList
-         return true
-       }else {
-         return false
-       }
-     }catch(err) {
-       //handles error
-       return false
-     }
- }
-
- return (
-   <div>
-     <FTUPage helperFunctions={
-       sendCoSignerInvitation: myCustomSendCoSignerInvitation,
-       sendCreatorConfirmation: myCustomSendCreatorConfirmation,
-       sendCreatorInitiation: myCustomsendCreatorInitiation,
-       sendCreatorSigned: myCustomSendCreatorSigned,
-       sendCreatorCompleted: myCustomSendCreatorCompleted,
-       sendCreatorAcceptance: myCustomSendCreatorAcceptance,
-       sendCreatorRejection: myCustomSendCreatorRejection
-     } />
-   </div>
- );
+import React from "react";
+import { FTUPage } from "@verified-network/verified-custody";
+
+function App() {
+  const myCustomSendCoSignerInvitation = async (
+    channel: "sms" | "email",
+    cosigerId: string,
+    cretorId: string,
+    hashedCretorPin: string
+  ): Promise<boolean> => {
+    // Implementation as above
+  };
+
+  const myCustomSendCreatorConfirmation = async (
+    channel: "sms" | "email",
+    cretorId: string,
+    cosigersList: [],
+    requiredSigners: number
+  ): Promise<boolean> => {
+    // Implementation as above
+  };
+
+  return (
+    <div>
+      <FTUPage
+        helperFunctions={{
+          sendCoSignerInvitation: myCustomSendCoSignerInvitation,
+          sendCreatorConfirmation: myCustomSendCreatorConfirmation,
+          sendCreatorInitiation: myCustomsendCreatorInitiation,
+          sendCreatorSigned: myCustomSendCreatorSigned,
+          sendCreatorCompleted: myCustomSendCreatorCompleted,
+          sendCreatorAcceptance: myCustomSendCreatorAcceptance,
+          sendCreatorRejection: myCustomSendCreatorRejection,
+        }}
+      />
+    </div>
+  );
 }
 ```
 
-### Existing/Returning Users
+# 🔄 Existing/Returning Users
 
 ```jsx
-import React from 'react';
-
-import { EnterPinPage} from '@verified-network/verified-custody';
-
-function App(){
-
-const myCustomSendCoSignerInvitation = async(
- channel: "sms" | "email",
- cosigerId: string,
- cretorId: string,
- hashedCretorPin: string
- ) => Promise<boolean> {
-     try {
-       //sends email/messages depending on the channel
-       if(channel === "sms") {
-         //send message to cosigerId phone number using creatorId and hashedCretorPin in message
-         return true
-       }else if(channel === "email") {
-         //send message to cosigerId email using creatorId and hashedCretorPin in message
-         return true
-       }else {
-         return false
-       }
-     }catch(err) {
-       //handles error
-       return false
-     }
- }
-
- const myCustomSendCreatorConfirmation = async(
-   channel: "sms" | "email",
-   cretorId: string,
-   cosigersList: [],
-   requiredSigners: number
- ) => Promise<boolean> {
-     try {
-       //sends email/messages depending on the channel
-       if(channel === "sms") {
-         //send message to cretorId phone number  showing creator his coSigners list and rule of signer using requiredSigners and totalNumber of coSignersList
-         return true
-       }else if(channel === "email") {
-          //send message to cretorId email showing creator his coSigners list and rule of signer using requiredSigners and totalNumber of coSignersList
-         return true
-       }else {
-         return false
-       }
-     }catch(err) {
-       //handles error
-       return false
-     }
- }
-
- return (
-   <div>
-     <EnterPinPage helperFunctions={
-       sendCoSignerInvitation: myCustomSendCoSignerInvitation,
-       sendCreatorConfirmation: myCustomSendCreatorConfirmation,
-       sendCreatorInitiation: myCustomsendCreatorInitiation,
-       sendCreatorSigned: myCustomSendCreatorSigned,
-       sendCreatorCompleted: myCustomSendCreatorCompleted,
-       sendCreatorAcceptance: myCustomSendCreatorAcceptance,
-       sendCreatorRejection: myCustomSendCreatorRejection
-     } />
-   </div>
- );
+import React from "react";
+import { EnterPinPage } from "@verified-network/verified-custody";
+
+function App() {
+  const myCustomSendCoSignerInvitation = async (
+    channel: "sms" | "email",
+    cosigerId: string,
+    cretorId: string,
+    hashedCretorPin: string
+  ): Promise<boolean> => {
+    // Implementation as above
+  };
+
+  const myCustomSendCreatorConfirmation = async (
+    channel: "sms" | "email",
+    cretorId: string,
+    cosigersList: [],
+    requiredSigners: number
+  ): Promise<boolean> => {
+    // Implementation as above
+  };
+
+  return (
+    <div>
+      <EnterPinPage
+        helperFunctions={{
+          sendCoSignerInvitation: myCustomSendCoSignerInvitation,
+          sendCreatorConfirmation: myCustomSendCreatorConfirmation,
+          sendCreatorInitiation: myCustomsendCreatorInitiation,
+          sendCreatorSigned: myCustomSendCreatorSigned,
+          sendCreatorCompleted: myCustomSendCreatorCompleted,
+          sendCreatorAcceptance: myCustomSendCreatorAcceptance,
+          sendCreatorRejection: myCustomSendCreatorRejection,
+        }}
+      />
+    </div>
+  );
 }
 ```
+
+## Summary
+
+- Secure blockchain wallet custody with private key sharding and on-chain encrypted storage.
+- Eliminates the need for mnemonic phrases or private key backups.
+- Supports multi-signature wallets via co-signers.
+- Provides complete workflows for **First Time Users** (FTU) and **Returning Users** (RU).
+- Fully customizable via React component props and helper functions.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@verified-network/verified-custody",
-  "version": "0.3.6",
+  "version": "0.3.7",
   "description": "React submodule for Custody of digital assets",
   "main": "dist/index.js",
   "module": "dist/index.mjs",