@verified-network/verified-custody 0.1.9 → 0.2.1

package/README.md

@@ -1,93 +1,437 @@
 # Verified Custody
 
-This react module allows users to create a vault using Mobile/ E-mail as their vault id and gives you a private Key which the users can use to sign all transactions further.
+Verified Custody is a react submodule for Custody of digital assets. This react module allows users to create Blockchain wallets using PHONE NUMBER/EMAIL and save the secured version on the wallet keys on-chain. It provides extra layer of security by utilizing Co-Signers protocol where users can add up to 5 other users/non-users as their trusted Co-Signers, these custodians serve as signers that can help recover your account keys and sign transactions.
+
+### Installation:
+
+```
+npm install @verified-network/verified-custody
+```
+
+```jsx
+import React from "react";
+
+import { VerifiedCustody } from "@verified-network/verified-custody";
+
+function App() {
+  return (
+    <div>
+      <VerifiedCustody />
+    </div>
+  );
+}
+```
 
 ### Build:
+
+- 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.
 
+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
 
-###  Install: 
-``` npm install @verified-network/verified-custody```
+\***\*< VerifiedCustody />\*\*** component is the completed workflow of the custody module, it handles full workflow for new and existing users in steps; it consists of:
 
- 
-The react module exports some constants and helper functions which will be useful when changing UI based on a user's state or any business logic
+# First Time Users
 
- **IS_CUSTODY_SET - (bool)** - Returns true when the user's pk is stored in the device and is validated by the users pin.
+\***\*< FTUPage />\*\*** component which handles full workflow for First Time Users. This consists of:
 
- **useCustody() - (hook)** - contains vaultInfo and IS_CUSTODY_SET.
+\***\*< 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).
 
- **initializeMessaging() - (void)** - Should be called to initialise the fcm which will get the device token. Should be called at the earliest.
+\***\*< OTPPage />\*\*** component which is where new/existing users verify and resend OTP.
 
-**getPermissionStatus - (bool** - Returns the status whether the user has allowed Push notification permissions. 
+\***\*< CreatePinPage />\*\*** component which is where all users either;
 
-**getFcmToken - ( string)** - Returns the FCM token of the device.
+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.
 
+\***\*< 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.
 
+# Returning Users
 
+\***\*< EnterPinPage />\*\*** component which is where existing/returning users gets to input their account pin to perform various actions like;
 
+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
 
-****< StartCustody />**** component is the entry component, which starts from asking the user to enter their phone/email and follows. 
+## Usage:
 
-This **< StartCustody />** component, can be used for multiple use case like to Sign Transactions and Retrieve Private Key by passing props.
+Note: To implement this module in your project there are some important component props required.
 
-- Create a new vault
-- To Accept and Decline Cosigner Request
-- To Sign Transactions
+# Components Props Type:
 
-**creator, txId, transactionType, user(id), etc.,** will be obtained from the notification params and as the query params.
+```jsx
+export interface VerifiedCustodyProps {
+  action?: VerifiedWalletAction;
+  actionText?: string;
+  origin?: string;
+  title?: string;
+  chainId?: number;
+  vaultData?: VerifiedWalletVault;
+  txData?: VerifiedWalletTx;
+  reqVaultData?: VerifiedWalletVault;
+  delayPageElement?: React.JSX.Element;
+  delayPageStyle?: React.CSSProperties;
+  helperFunctions?: VerifiedCustodyHelpers;
+}
 
-## Usage:
+export type VerifiedWalletAction =
+  | "connect_wallet"
+  | "getPk"
+  | "invitation"
+  | "signRecovery"
+  | "completeRecovery";
+
+export type VerifiedWalletVault = {
+  vaultId: string,
+  hashedVaultId?: string,
+  hashedVaultPin?: string,
+  CoSignerId?: string,
+  vId?: string,
+  vPh?: string,
+  cId?: string,
+  address?: string,
+  channel?: "sms" | "email",
+  pk?: string,
+};
+
+export type VerifiedWalletTx = {
+  id: string,
+};
+
+export interface VerifiedCustodyHelpers {
+  sendCoSignerInvitation: (
+    channel: "sms" | "email",
+    cosigerId: string,
+    cretorId: string,
+    hashedCretorPin: string
+  ) => Promise<boolean>;
+
+  sendCreatorConfirmation: (
+    channel: "sms" | "email",
+    cretorId: string,
+    cosigersList: [],
+    requiredSigners: number
+  ) => Promise<boolean>;
+
+  sendCreatorInitiation: (
+    channel: "sms" | "email",
+    cretorId: string,
+    hashedCretorPin: string,
+    txId: number,
+    requiredSigners: number
+  ) => Promise<boolean>;
+
+  sendCreatorSigned: (
+    channel: "sms" | "email",
+    cretorId: string,
+    coSignerId: string
+  ) => Promise<boolean>;
+
+  sendCreatorCompleted: (
+    channel: "sms" | "email",
+    cretorId: string,
+    txId: number
+  ) => Promise<boolean>;
+
+  sendCreatorAcceptance: (
+    channel: "sms" | "email",
+    creatorId: string,
+    coSignerId: string
+  ) => Promise<boolean>;
+
+  sendCreatorRejection: (
+    channel: "sms" | "email",
+    creatorId: string,
+    coSignerId: string
+  ) => Promise<boolean>;
+}
+```
+
+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.
+
+Check the code Below for better explaination of how all helper functions work.
+
+### Full workflow with one component(handle First time users, existing user and all type of actions)
+
+```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>
+ );
+}
+```
+
+### 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>
+ );
+}
+```
+
+### Existing/Returning Users
+
+```jsx
+import React from 'react';
+
+import { EnterPinPage} from '@verified-network/verified-custody';
+
+function App(){
 
-### Creating a vault:
-
-    return (
-        <>
-          { IS_CUSTODY_SET ? (
-            <div>Welcome to dashboard</div>
-          ) : permissionStatus === "granted" ? (
-            <>
-              { fcmToken ? (
-                <StartCustody creatorInfo={{ fcmToken }} />
-              ) : (
-                <div>Retrieving fcm token...</div>
-              ) }
-            </>
-          ) :  permissionStatus === 'denied' ? (
-              <p>
-                Notifications are blocked. Please enable them from your browser
-                settings.
-              </p>
-          ) : (
-            <div>Requesting notification permissions...</div>
-          )}
-        </>
-      )
-
-
-### Handling cosigner requests:
-
-        <StartCustody
-            startPoint={{
-                component: "StartCosigner",  // currently supports all forms of signing
-                args: { creator, txId, transactionType, id },
-            }}
-        />
-    
-*transactionType* determines the type of signing request. 
-
-
-
-### Recovering a private key:
-
-This **< GetPrivateKey  />** component, will let you to retreive the private key once all your cosigners signoff your recovery code request.
-
-    return (
-    <GetPrivateKey
-      setupProps={{
-        chainId: 84532,
-      }}
-      signingInfo={{ creator, txId, transactionType, user }}
-     />
-    )
+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>
+ );
+}
+```

package/dist/index.d.mts

@@ -0,0 +1,165 @@
+import React$1 from 'react';
+
+type VerifiedWalletAction = "connect_wallet" | "getPk" | "invitation" | "signRecovery" | "completeRecovery";
+type VerifiedWalletVault = {
+    vaultId: string;
+    hashedVaultId?: string;
+    hashedVaultPin?: string;
+    CoSignerId?: string;
+    vId?: string;
+    vPh?: string;
+    cId?: string;
+    address?: string;
+    channel?: "sms" | "email";
+    pk?: string;
+};
+type VerifiedWalletTx = {
+    id: string;
+};
+interface VerifiedCustodyProps {
+    action?: VerifiedWalletAction;
+    actionText?: string;
+    origin?: string;
+    title?: string;
+    chainId?: number;
+    vaultData?: VerifiedWalletVault;
+    txData?: VerifiedWalletTx;
+    reqVaultData?: VerifiedWalletVault;
+    delayPageElement?: React.JSX.Element;
+    delayPageStyle?: React.CSSProperties;
+    helperFunctions?: VerifiedCustodyHelpers;
+}
+interface VerifiedCustodyHelpers {
+    sendCoSignerInvitation: (channel: "sms" | "email", cosigerId: string, cretorId: string, hashedCretorPin: string) => Promise<boolean>;
+    sendCreatorConfirmation: (channel: "sms" | "email", cretorId: string, cosigersList: [], requiredSigners: number) => Promise<boolean>;
+    sendCreatorInitiation: (channel: "sms" | "email", cretorId: string, hashedCretorPin: string, txId: number, requiredSigners: number) => Promise<boolean>;
+    sendCreatorSigned: (channel: "sms" | "email", cretorId: string, coSignerId: string) => Promise<boolean>;
+    sendCreatorCompleted: (channel: "sms" | "email", cretorId: string, txId: number) => Promise<boolean>;
+    sendCreatorAcceptance: (channel: "sms" | "email", creatorId: string, coSignerId: string) => Promise<boolean>;
+    sendCreatorRejection: (channel: "sms" | "email", creatorId: string, coSignerId: string) => Promise<boolean>;
+}
+
+declare const VerifiedCustody: (props: VerifiedCustodyProps) => React$1.JSX.Element;
+
+declare const FTUPage: (props: {
+    fontsLoaded?: boolean;
+    popupView?: boolean;
+    action?: string;
+    vaultData?: any;
+    txData?: any;
+    chainId?: number;
+    defaultCountry?: {
+        area: string;
+        flag: string;
+        name: string;
+    };
+    showLogoPage?: boolean;
+    logoPageElement?: React$1.JSX.Element;
+    logoTimeoutTime?: number;
+    showStartupPage?: boolean;
+    startupPageElement?: React$1.JSX.Element;
+    setisOnboard?: (isOnboard: boolean) => void;
+    helperFunctions?: VerifiedCustodyHelpers;
+}) => React$1.JSX.Element;
+
+declare const EnterPinPage: (props: {
+    fontsLoaded?: boolean;
+    setisOnboard: (isOnboard: boolean) => void;
+    vaultId: string;
+    hashedVaultId: string;
+    encrptedPk: string;
+    vaultAddress: string;
+    vaultChannel: "sms" | "email";
+    actionText?: string;
+    title?: string;
+    origin?: string;
+    chainId?: number;
+    newChainId?: number;
+    action?: string;
+    reqVaultData?: any;
+    reqTxData?: any;
+    setIsLoading: (isLoading: boolean) => void;
+    helperFunctions?: VerifiedCustodyHelpers;
+}) => React$1.JSX.Element;
+
+declare const CreatePinPage: (props: {
+    setStep: (step: string) => void;
+    setIsLoading: (isLoading: boolean) => void;
+    setShowSuccessBtn: (showSuccessBtn: boolean) => void;
+    setSuccessBtnText: (successBtnText: string) => void;
+    setSuccessBtnNeutText: (successBtnNeutText: string) => void;
+    setSuccessBtnFunc: (successBtnFunc: any) => void;
+    setSuccessBtnNeutFunc: (successBtnNeutFunc: any) => void;
+    setActionHeaderText: (actionHeaderText: string) => void;
+    setActionFooterText: (actionFooterText: string) => void;
+    userNumberFmt: string;
+    userEmail: string;
+    selectedCountry: {
+        name: string;
+        area: string;
+        flag: string;
+    };
+    action?: string;
+    vaultData?: any;
+    txData?: any;
+    helperFunctions?: VerifiedCustodyHelpers;
+}) => React$1.JSX.Element;
+
+declare const ContactPage: (props: {
+    setStep: (step: string) => void;
+    setIsLoading: (isLoading: boolean) => void;
+    setUserNumberFmt: (number: string) => void;
+    userNumberFmt: string;
+    setUserEmail: (email: string) => void;
+    userEmail: string;
+    setSelectedCountry: (country: {
+        name: string;
+        area: string;
+        flag: string;
+    }) => void;
+    selectedCountry: {
+        name: string;
+        area: string;
+        flag: string;
+    };
+    allCountries: any;
+}) => React$1.JSX.Element;
+
+declare const OTPPage: (props: {
+    setStep: (step: string) => void;
+    setIsLoading: (isLoading: boolean) => void;
+    setUserNumberFmt: (number: string) => void;
+    setUserEmail: (email: string) => void;
+    selectedCountry: {
+        name: string;
+        area: string;
+        flag: string;
+    };
+    userNumberFmt: string;
+    userEmail: string;
+}) => React$1.JSX.Element;
+
+declare const AddCosignersPage: (props: {
+    setStep: (step: string) => void;
+    setIsLoading: (isLoading: boolean) => void;
+    userNumberFmt: string;
+    userEmail: string;
+    selectedCountry: {
+        name: string;
+        area: string;
+        flag: string;
+    };
+    allCountries: any;
+    defaultCountry?: {
+        area: string;
+        flag: string;
+        name: string;
+    };
+    helperFunctions?: VerifiedCustodyHelpers;
+}) => React$1.JSX.Element;
+
+declare const hashTheString: (text: string) => string;
+declare const encryptString: (text: string, secretKey: string) => string;
+declare const decryptString: (encryptedText: string, secretKey: string) => string;
+
+export { AddCosignersPage as AddCoSignersPage, ContactPage, CreatePinPage, EnterPinPage, FTUPage, OTPPage, VerifiedCustody, decryptString, encryptString, hashTheString };