8. SDK API Reference

The SurferMonkey SDK offers a comprehensive set of functions to facilitate blockchain interactions with a privacy-preserving focus. This chapter provides in-depth documentation for each core method in the SDK, including descriptions, parameter details, and example usage.

warning

• getInstitutionMembershipProof must be called from the institution's server to protect user privacy. Note: "backend" in the API refers to the SurferMonkey backend, not the institution's server.
• In a production environment, all code is executed within the SDK itself, eliminating the need for the SurferMonkey backend and reducing potential security vectors.

Figure 5 illustrates the workflow for obtaining the user institution membership proof in a secure and privacy-preserving manner. First, Alice sends her address to the Institution Server. The Institution Server then calls the getInstitutionMembershipProof function to generate a cryptographic proof of Alice's membership within the institution's whitelist. Finally, the server sends the resulting userMerkleProof back to Alice. This ensures that Alice only receives the proof related to her own membership, safeguarding the privacy of other users.

Figure 7. - Institution Membership Proof Workflow

Depending on the institution and custodian configuration, Alice may call createDeposit() and createWithdraw() directly from her own device, or these functions may be executed on the institution's server. However, to maintain privacy, the getInstitutionMembershipProof function must always be called by the Institution Server to protect the confidentiality of all users.

Core API Methods

The core methods are essential for integrating with the SurferMonkey infrastructure, simplifying processes such as deposits, withdrawals, and zero-knowledge proof (ZKP) generation.

createDeposit()

• Description: Generates a deposit object based on the user's message. This is the first step in locking assets into the Universal Plugin, involving data validation and backend integration.
• Parameters:
  • BACKEND_RPC (string): The SurferMonkey backend RPC URL.
  • userMessage (object): The user message JSON containing transaction details such as userEOA, inputTx, and outputTxArr.
  • verbose (boolean): If true, logs verbose information during the deposit creation.
• Example Call:

  const deposit = await SurferMonkey.createDeposit({
    BACKEND_RPC: "https://backend-rpc-url",
    userMessage,
    verbose: true
  });
• Expected Response: Returns a JSON object containing the structure of the deposit, including SOLIDITY_DATA required for blockchain interaction.

createWithdraw()

• Description: Generates a Zero-Knowledge Proof (ZKP) to ensure the privacy of transaction details, enabling secure fund withdrawal from the Universal Plugin.
• Parameters:
  • BACKEND_RPC (string): The SurferMonkey backend RPC URL.
  • depositJSON (object): The JSON object returned by createDeposit().
  • targetLeafChild (number): Specifies the output transaction index to withdraw.
  • verbose (boolean): If true, logs detailed information during the proof generation.
• Example Call:

  const zkpSolidityData = await SurferMonkey.createWithdraw({
    BACKEND_RPC,
    depositJSON: deposit,
    targetLeafChild: 0,
    verbose: true
  });
• Expected Response: Returns ZKP in a Solidity-compatible format (SOLIDITY_DATA).

---

Additional Methods

getInstitutionMembershipProof()

• Description: Generates a cryptographic proof that demonstrates a user's membership in an institution's whitelist using the Merkle Tree structure.
• Parameters:
  • BACKEND_RPC (string): The SurferMonkey backend RPC URL.
  • userEOA (string): User's EVM address in Hex format.
  • institutionLeaves (Array of strings): Array of EVM addresses representing the users in the institution's whitelist.
• Example Call:

  const userMerkleProof = await SurferMonkey.getInstitutionMembershipProof({
    BACKEND_RPC: "https://backend-rpc-url",
    userEOA: "0xUserAddressHere",
    institutionLeaves: [
      "0xValidUserAddress1",
      "0xUserAddressHere",
      "0xValidUserAddress3"
    ]
  });
• Expected Response: Returns an object containing the user's Merkle proof, demonstrating membership in the institution's whitelist.
• Usage Note: This proof should be included in the userMessage for transaction verification. It ensures that only authorized users interact with the protocol without exposing the entire institution whitelist to individual clients.

updatePayloadData()

• Description: Updates the User Intention Payload fields from the Deposit Object with the new updated Payload. This feature allows modifications to a target child within the deposit, such as changing smart contract call details while maintaining the locked amount, asset type, and user details.
• Parameters:
  • BACKEND_RPC (string): The SurferMonkey backend RPC URL.
  • newSmartContractCallOnTargetChild (Array[object]): Contains the new payload details for the child deposit.
  • depositJSON (object): The full deposit object with all child transactions.
  • targetLeafChild (number): Index value indicating which child deposit to modify.
• Example Call:

  const updatedDeposit = await SurferMonkey.updatePayloadData({
    BACKEND_RPC: "https://backend-rpc-url",
    newSmartContractCallOnTargetChild: 
    [
      {
        payloadAmountNative: "50000000000000000", // 0.05 ETH
        targetSC: "0xTargetSmartContractAddress",
        payloadObject: {
          functionHeader: "function transfer(address recipient, uint256 amount)",
          functionName: "transfer",
          payloadParmsArr: ["0xRecipientAddress", "50000000000000000"]
        }
      }
    ],
    depositJSON: deposit,
    targetLeafChild: 1
  });
• Expected Response: Returns an updated deposit object with modified payload fields, enabling dynamic flexibility in user actions.
• Usage Note: This method is essential for scenarios where users need to modify the intended actions, such as changing the recipient or altering parameters due to updated requirements.

---

Summary of Methods

Method	Purpose	Required Parameters
createDeposit()	Generate deposit object for locking funds	BACKEND_RPC, userMessage, verbose
createWithdraw()	Generate Zero-Knowledge Proof for withdrawal	BACKEND_RPC, depositJSON, targetLeafChild, verbose
getInstitutionMembershipProof()	Generate proof of user membership in institution	BACKEND_RPC, userEOA, institutionLeaves
updatePayloadData()	Update payload fields for a specific child deposit	BACKEND_RPC, newSmartContractCallOnTargetChild, depositJSON, targetLeafChild