@verified-network/verified-custody 0.2.0 → 0.2.2

package/README.md

@@ -0,0 +1,437 @@
+# 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. 
+
+### 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
+
+\***\*< VerifiedCustody />\*\*** component is the completed workflow of the custody module, it handles full workflow for new and existing users in steps; it consists of:
+
+# First Time Users
+
+\***\*< FTUPage />\*\*** component which handles full workflow for First Time Users. This consists of:
+
+\***\*< 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).
+
+\***\*< OTPPage />\*\*** component which is where new/existing users verify and resend OTP.
+
+\***\*< CreatePinPage />\*\*** component which is where all users either;
+
+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
+
+## Usage:
+
+Note: To implement this module in your project there are some important component props required.
+
+# Components Props Type:
+
+```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;
+}
+
+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(){
+
+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

@@ -1,11 +1,11 @@
 import React$1 from 'react';
 
-type VerifiedWalletAction = "connect_wallet" | "getPk" | "invitation" | "signRecovery" | "completeRecovery";
+type VerifiedWalletAction = "connect_wallet" | "getPk" | "invitation" | "signRecovery" | "completeRecovery" | null;
 type VerifiedWalletVault = {
     vaultId: string;
     hashedVaultId?: string;
     hashedVaultPin?: string;
-    CoSignerId?: string;
+    coSignerId?: string;
     vId?: string;
     vPh?: string;
     cId?: string;
@@ -28,6 +28,15 @@ interface VerifiedCustodyProps {
     delayPageElement?: React.JSX.Element;
     delayPageStyle?: React.CSSProperties;
     helperFunctions?: VerifiedCustodyHelpers;
+    popupView?: boolean;
+    defaultCountry?: {
+        area: string;
+        flag: string;
+        name: string;
+    };
+    showLogoPage?: boolean;
+    logoPageElement?: React.JSX.Element;
+    logoTimeoutTime?: number;
 }
 interface VerifiedCustodyHelpers {
     sendCoSignerInvitation: (channel: "sms" | "email", cosigerId: string, cretorId: string, hashedCretorPin: string) => Promise<boolean>;
@@ -60,6 +69,7 @@ declare const FTUPage: (props: {
     startupPageElement?: React$1.JSX.Element;
     setisOnboard?: (isOnboard: boolean) => void;
     helperFunctions?: VerifiedCustodyHelpers;
+    setIsLoading?: (isLoading: boolean) => void;
 }) => React$1.JSX.Element;
 
 declare const EnterPinPage: (props: {
@@ -162,4 +172,4 @@ 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 };
+export { AddCosignersPage as AddCoSignersPage, ContactPage, CreatePinPage, EnterPinPage, FTUPage, OTPPage, VerifiedCustody, type VerifiedCustodyHelpers, type VerifiedCustodyProps, type VerifiedWalletAction, type VerifiedWalletTx, type VerifiedWalletVault, decryptString, encryptString, hashTheString };

package/dist/index.d.ts

@@ -1,11 +1,11 @@
 import React$1 from 'react';
 
-type VerifiedWalletAction = "connect_wallet" | "getPk" | "invitation" | "signRecovery" | "completeRecovery";
+type VerifiedWalletAction = "connect_wallet" | "getPk" | "invitation" | "signRecovery" | "completeRecovery" | null;
 type VerifiedWalletVault = {
     vaultId: string;
     hashedVaultId?: string;
     hashedVaultPin?: string;
-    CoSignerId?: string;
+    coSignerId?: string;
     vId?: string;
     vPh?: string;
     cId?: string;
@@ -28,6 +28,15 @@ interface VerifiedCustodyProps {
     delayPageElement?: React.JSX.Element;
     delayPageStyle?: React.CSSProperties;
     helperFunctions?: VerifiedCustodyHelpers;
+    popupView?: boolean;
+    defaultCountry?: {
+        area: string;
+        flag: string;
+        name: string;
+    };
+    showLogoPage?: boolean;
+    logoPageElement?: React.JSX.Element;
+    logoTimeoutTime?: number;
 }
 interface VerifiedCustodyHelpers {
     sendCoSignerInvitation: (channel: "sms" | "email", cosigerId: string, cretorId: string, hashedCretorPin: string) => Promise<boolean>;
@@ -60,6 +69,7 @@ declare const FTUPage: (props: {
     startupPageElement?: React$1.JSX.Element;
     setisOnboard?: (isOnboard: boolean) => void;
     helperFunctions?: VerifiedCustodyHelpers;
+    setIsLoading?: (isLoading: boolean) => void;
 }) => React$1.JSX.Element;
 
 declare const EnterPinPage: (props: {
@@ -162,4 +172,4 @@ 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 };
+export { AddCosignersPage as AddCoSignersPage, ContactPage, CreatePinPage, EnterPinPage, FTUPage, OTPPage, VerifiedCustody, type VerifiedCustodyHelpers, type VerifiedCustodyProps, type VerifiedWalletAction, type VerifiedWalletTx, type VerifiedWalletVault, decryptString, encryptString, hashTheString };