Skip to main content

2. Installation and Setup

Option 1: Using .npmrc File​

  1. GitHub Token Setup:

    • Make sure you have a GitHub Personal Access Token (PAT) with the necessary permissions. Ensure it has read:packages and the repo scope.

  2. Add Token to .npmrc File:

    • Create or update your .npmrc file:

      @surfermonkey:registry=https://npm.pkg.github.com
      //npm.pkg.github.com/:_authToken=${GITHUB_TOKEN}

    • The ${GITHUB_TOKEN} is to access an Environment Variable.

  3. Set Your GitHub Token as Environment Variable:

    • Run the following command in the terminal from the root folder where your .npmrc file is located, replace MY_GITHUB_TOKEN with your actual token:

      export GITHUB_TOKEN=MY_GITHUB_TOKEN

  4. Install the SDK:

    • Run the following command to install the SDK:

      npm install @surfermonkey/sdk_babyulu
    note

    If the installation fails, it means the .npmrc file couldn't read the token from the environment variable. In that case, you can replace ${GITHUB_TOKEN} with your actual token directly in the .npmrc file.

    warning

    Be Careful: If you manually place your token in the .npmrc file, it will be saved in plaintext and could be unintentionally pushed to repositories. Consider adding .npmrc to your .gitignore file to prevent accidental exposure, and delete .npmrc file after installation.

Option 2: Direct Installation Command​

  1. GitHub Token Setup:

    • Make sure you have a GitHub Personal Access Token (PAT) with the necessary read:packages and the repo permissions.

  2. Install the SDK:

    • Run the following command to install directly from GitHub without needing a .npmrc file:

      npm install https://GITHUB_TOKEN@github.com/SurferMonkey/SDK_BabyUlu.git

    • Replace GITHUB_TOKEN with your actual GitHub Personal Access Token.

Option 3: Cloning the Repository Manually​

  1. Clone the Repository:

    • Make sure you have a GitHub Personal Access Token (PAT) with the necessary read:packages and the repo permissions.

    • Clone the SDK repository from GitHub:

      git clone https://github.com/SurferMonkey/SDK_BabyUlu.git

  2. Copy the SDK Folder:

    • Navigate to the cloned repository and copy the SDK folder into your project.

  3. Import the SDK:

    • Import the required SDK files into your code as needed.

Troubleshooting Installation Issues

  • Authentication Problems: Ensure the GitHub PAT has read:packages and the repo permissions.
  • Installation Failures: Double-check your .npmrc configuration and ensure you are logged in with the correct GitHub credentials.
danger

Keep GitHub YOUR_PERSONAL_ACCESS_TOKEN private. Do not share it.

Initial Configuration​

Adding Your User EVM Addresses (institutionLeaves)

  • To validate users and ensure only authorized participants can interact with the SurferMonkey protocol, you need to define a list of authorized user addresses.

  • Create a list (institutionLeaves) of all your users EOA (signers) EVM addresses in JSON array format:

    [
      "0xYourEvmAddressHere",
      "0xSomeEvmAddressHere"
    ]

  • This step helps validate that each transaction is authorized by a whitelisted institution or user.

Institutional Onboarding​

SurferMonkey is designed to streamline onboarding for institutions, ensuring that privacy and compliance are integrated seamlessly into blockchain activities. This section guides you through the institutional onboarding process.

Step 1: Receive Institutional Credentials

  • Institutions need credentials to interact with the SurferMonkey protocol, including:
    • RPC URL for SDK use.
    • Username and password for the regulatory dashboard.
    • Institution ID and a set of elliptic encryption key pairs (public and private keys).

Step 2: Configure Institution Admin

  • Identify an EVM address that will act as the "Institution Admin".
  • SurferMonkey will whitelist this admin, allowing it to manage access for institution users autonomously.
info

Important Note: Only your Institution Admin Address is authorized to update the Merkle Root of your Client Users. This ensures that only verified institution representatives can modify access permissions, enhancing the security and integrity of your setup.

Step 3: Managing User Access

  • The institution admin can grant access to its users without further involvement from SurferMonkey.
  • Users share the institution’s public key, while private keys remain secured within the institution.
  • To whitelist users, the institution admin can call a function on the Universal Plugin Smart Contract, leveraging a Merkle tree structure to batch and optimize the onboarding of multiple users at once.

Step 4: Update Authorized Users Using Merkle Trees

  • When onboarding new users or updating the list of authorized users, the institution creates a Merkle tree of client EVM addresses.
  • The institution admin pairs its Poseidon Hash(encryption public key) with the root of the institution’s client Merkle tree, registering it on the Universal Plugin Smart Contract.

Code Snippet: Updating Your Clients’ Merkle Root
The following example demonstrates how to programmatically update the institution’s client Merkle root with SurferMonkey SDK using JavaScript. This step pairs your institution's public key with your updated Merkle root, ensuring your clients are correctly registered on the Universal Plugin Smart Contract.

  • Step 1: Update the institution's root with a new list of authorized users by passing the institution's public key and user addresses to institutionRootUpdate.
  • Step 2: Pair the updated root with the institution's public key by submitting a transaction to the Universal Plugin Smart Contract.
const SurferMonkey = require('@surfermonkey/sdk_babyulu'); // Import the SurferMonkey SDK

// Your public key from SurferMonkey credentials
const PUB_KEY = [
    "PubKeyString[0]",
    "PubKeyString[1]"
];

// An array of your users' EVM addresses (Externally Owned Accounts)
const institutionLeaves = [
    "0xAddressAlice",
    "0xAddressBob"
];

// Step 1: Update institution root with client addresses
const updateObject = await SurferMonkey.institutionRootUpdate({
  BACKEND_RPC,
  pubKey: PUB_KEY,
  institutionLeaves
});

// Step 2: Register the updated root with the Universal Plugin Smart Contract
const UniversalPlugin_SC = new ethers.Contract(UniversalPluginAddress, UP_ABI, ADMIN_SIGNER);
const submitTx = await UniversalPlugin_SC.PairMyInstitutionRootWithMyPubKey(
    updateObject.root,
    updateObject.pubKeyHash,
    {
        maxPriorityFeePerGas: Number(25000000000),
        maxFeePerGas: Number(27000000000)
    }
);

console.log("Transaction submitted:", submitTx.hash);

Institution Whitelisting and Merkle Trees​

To facilitate privacy, compliance, and efficiency in managing users, SurferMonkey leverages Merkle Trees to whitelist users for the protocol.

  • Merkle Trees for User Management:
    Institutions need to maintain a list of their users as Merkle Tree leaves. By using a Merkle Tree, institutions can batch update user access rather than making individual updates for each user. This approach reduces the number of on-chain transactions and optimizes the onboarding process.

  • Updating Client Users Merkle Root:
    Only the Institution Admin Address is authorized to update the Merkle Root of the Client Users. The Institution Admin can pair the Merkle root of its users with its public key hash using the Universal Plugin Smart Contract.

  • Batch Whitelisting Process:
    Instead of making individual on-chain calls to whitelist each user, institutions generate a Merkle root of the list of valid user addresses and submit it in one transaction. This root is linked with the Institution’s public key to verify authenticity.

Generating User Merkle Proofs​

The getInstitutionMembershipProof function is used to generate the proof that a particular user address is a valid member of the institution. It is crucial that the institution backend handles this process securely to protect user privacy.

  • Generate the User Merkle Proof:
    The institution should call the getInstitutionMembershipProof function, providing the user's Ethereum address and the full list of whitelisted addresses (institutionLeaves). The generated proof (userMerkleProof) can then be securely provided to the user client.

    const userMerkleProof = await SurferMonkey.getInstitutionMembershipProof({
      BACKEND_RPC,
      userEOA: EOA_Address,
      institutionLeaves
    });

    This ensures that the user’s client only provides the proof (userMerkleProof) without needing access to the entire list of institution members (institutionLeaves), enhancing privacy.