Protocol SDK - The Deed Protocol

This repository contains the Typescript SDK for building frontend interfaces that interact with the Smart Contracts of The Deed Protocol. The SDK abstracts the complexities of direct blockchain interactions and provides a robust, easy-to-use interface for integrating protocol functionalities into your applications.

Overview

The Protocol SDK is designed to simplify the development of user interfaces that communicate with The Deed Protocol’s smart contracts. By providing a set of well-defined, type-safe functions and interfaces, the SDK allows developers to:

• Connect to Protocol Smart Contracts: Seamlessly interact with on-chain contracts responsible for tokenizing real world assets.
• Perform Transactions: Call functions for minting, validating, and managing property deeds without dealing directly with low-level contract details.
• Handle Events: Easily subscribe to and process blockchain events, ensuring your frontend remains synchronized with on-chain activities.
• Integrate Wallets: Use familiar wallet providers to sign transactions and authenticate users.

For full context on the underlying smart contracts, refer to the Protocol Smart Contracts repository.

Key Components

1. Contract Interfaces

The SDK includes comprehensive interfaces for interacting with the core Protocol Smart Contracts. These interfaces are designed to mirror the functionality of the on-chain contracts while providing a simplified, type-safe abstraction.

• DeedNFT Interface:
  Interact with the core ERC721 token contract that represents real estate deeds. This interface allows you to mint tokens, retrieve metadata, and perform other NFT-related operations.

• Validator & ValidatorRegistry Interfaces:
  Work with the validation system by calling functions to validate deed data, manage validators, and retrieve operating agreements. These interfaces ensure that your frontend can easily access and display validated property information.

• FundManager Interface:
  Access functionalities related to managing and distributing funds generated by protocol activities. This includes operations for handling transaction fees and disbursing payments to relevant parties.

2. Transaction Utilities

The SDK provides utility functions to streamline the process of sending transactions, handling confirmations, and managing errors. These utilities abstract common tasks such as:

• Transaction Signing:
  Integrating with wallet providers to securely sign and send transactions.

• Receipt Handling:
  Waiting for confirmations and processing transaction receipts to update your frontend state.

3. Event Handlers

Stay up-to-date with on-chain events by subscribing to notifications from the Protocol Smart Contracts. The built-in event handlers allow you to:

• Listen to Key Events:
  Such as token transfers, validations, and fund disbursements.

• Update UI in Real-Time:
  Automatically reflect blockchain changes in your application interface.

4. Utility Functions and Helpers

Additional helper functions assist with common tasks such as:

• Data Formatting:
  Converting raw blockchain data into human-readable formats.

• Error Management:
  Handling exceptions and providing meaningful feedback to users during blockchain interactions.

Features

• Type Safety:
  Written entirely in Typescript, ensuring robust, maintainable code with fewer runtime errors.

• Simplified Contract Interactions:
  High-level functions encapsulate the complexity of direct smart contract calls, reducing development time.

• Event Subscription:
  Built-in support for subscribing to and handling blockchain events, keeping your UI in sync with on-chain activity.

• Comprehensive Documentation:
  Detailed inline documentation and clear interfaces to help you quickly understand and utilize the SDK.

• Seamless Wallet Integration:
  Easy integration with popular wallet providers for secure user authentication and transaction signing.

Installation and Setup

Prerequisites

• Node.js v16+
• Yarn or npm
• A modern browser with wallet support (e.g., MetaMask) for interacting with live networks

Installation

1. Clone the Repository:

   git clone https://github.com/Deed3Labs/ProtocolSDK.git
   cd ProtocolSDK

2. Install Dependencies:

   npm install
   # or if using Yarn:
   yarn install

3. Build the SDK:

   npm run build
   # or if using Yarn:
   yarn build

Usage

Integrating the SDK in Your Project

After installing the SDK, import the necessary modules into your frontend application. Below is an example of how to instantiate and use the SDK to interact with the DeedNFT contract:

import { DeedNFT } from '@deed3labs/protocol-sdk';
import { ethers } from 'ethers';

// Initialize a provider (using MetaMask, for example)
const provider = new ethers.providers.Web3Provider(window.ethereum);

// Define the deployed contract address (update with your network’s contract address)
const deedNFTAddress = '0xYourDeployedDeedNFTContractAddress';

// Instantiate the DeedNFT interface
const deedNFT = new DeedNFT(provider, deedNFTAddress);

// Example: Retrieve metadata for a specific token ID
async function getDeedMetadata(tokenId: number) {
  try {
    const metadata = await deedNFT.getMetadata(tokenId);
    console.log('Deed Metadata:', metadata);
  } catch (error) {
    console.error('Error fetching metadata:', error);
  }
}

// Call the function with a token ID of your choice
getDeedMetadata(1);

Handling Transactions and Events

The SDK also provides helper functions to manage transactions and subscribe to smart contract events. Check out the documentation within the SDK source for further examples and best practices.

Testing

Run the included test suite to ensure that the SDK functions correctly:

npm run test
# or if using Yarn:
yarn test

Tests are implemented using a modern testing framework and cover core functionalities such as contract calls, event subscriptions, and transaction handling.

License

The Protocol SDK is licensed under the AGPL-3.0. For more details, please refer to the LICENSE file.