Buyback Fraction Market

This guide provides a step-by-step overview for setting up a fraction platform with buyback functionality using the Fraction Protocol. It outlines the necessary facets for platform configuration and explains how to correctly initialize the proxy’s storage for Buyback Fraction Market applications.

The buyback is the process in which a borrower (issuer) creates fraction tokens (ERC-20/1155) to raise capital by selling them to investors. The borrower must then repay the debt, with interest, within a specified time window.

When you create a new campaign you can set the buyback duration and interest:

• Interest – An additional amount the borrower (issuer) must repay to on-chain investors upon buyback, calculated based on a predetermined interest rate as a return for providing capital.
• Buyback duration – A time window during which a borrower (issuer) must repay the debt provided by on-chain investors. If the debt is not repaid within the specified time window, the borrower is liquidated and their real-world assets are sold for fiat currency. The realized gains from the liquidation are converted into the campaign’s supported cryptocurrency and returned to investors.

Buyback Flow

The buyback flow represents a set of scenarios where a campaign can navigate through, where each scenario yields a specific result or destination point. These scenarios are dictated by the selected facets and their setup when deploying a platform.

Scenarios of the campaign are regulated by:

1. The buying power of the on-chain investors — how much capital is provided to the borrower (issuer).
2. The ability of the borrower (issuer) to repay the debt in the specified time window.

Facets

The following table outlines the required facets to integrate into the Diamond proxy for enabling the Buyback Fraction Market use case. For details on each facet’s functionality, refer to the respective documentation below.

Instructions

Setting Up The Environment

Create a new directory and initialize the Node project by running:

npm init

Install the Typescript and TS execution engine:

npm install --save-dev typescript ts-node

Install the Hardhat npm package:

npm install hardhat 

Begin by initializing the Hardhat project. When prompted, confirm each option by entering Y (yes) for all configuration choices.

npx hardhat init

Then install all necessary dependencies required for smart contract deployment:

npm install @solidstate/contracts @nomicfoundation/hardhat-toolbox ethers

In your project root folder find the tsconfig.json file and add the resolveJsonModule property to your configuration and set it to true:

{
  "compilerOptions": {
    "resolveJsonModule": true
    /// ... other properties
  }
}

This property ensures that Typescript can read the data from the .json files.

Diamond Proxy Deployment

In your project, find the contracts folder and, inside it, create a new file that will contain the implementation of the diamond proxy smart contract. For demonstration purposes, the name of the file will be MyDiamond.sol.

Insert the following code into the MyDiamond.sol file:

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.27;
 
import "./proxy/diamond/SolidstateDiamondProxy.sol";
 
contract FractionDiamond is SolidStateDiamond {}

In the root folder of your project, create a new TypeScript file called deploy.ts. This file will contain the code required to:

1. Deploy the diamond proxy smart contract.
2. Add facets and initialize the diamond storage.

Insert the code provided below into the deploy.ts file and follow the comments.

import { ethers } from "hardhat";
// 1. Import the FractionDiamond.json file to read the ABI and the Bytecode.
import SolidStateDiamond from "./artifacts/contracts/MyDiamond.sol/FractionDiamond.json"
 
// 2. Set up provider (using a testnet like Sepolia). 
// Ensure you have set up the environment variable that contains the provider details.
const provider = new ethers.JsonRpcProvider(process.env.SEPOLIA_RPC);
 
// 3. Set up wallet (replace with your private key).
const wallet = new ethers.Wallet("0xffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff", provider);
 
// 4. Define ABI and Bytecode.
const abi = SolidStateDiamond.abi
const bytecode = SolidStateDiamond.bytecode
 
// 5. Initialize the variable for the diamond proxy address.
let diamondAddress: string;
 
// 6. Create a ContractFactory
const contractFactory = new ethers.ContractFactory(abi, bytecode, wallet);
 
// 7. Deploy the contract 
async function deployContract() {
  console.log("Deploying contract...");
 
  // 8. Deploy the contract
  const contract = await contractFactory.deploy();
 
  // 9. Wait for deployment to be mined
  await contract.waitForDeployment();
  console.log("Contract deployed at:", contract.target);
  diamondAddress = contract.target
}
 
deployContract().catch(console.error);

Deploy the diamond proxy smart contract by running it in your terminal:

npx hardhat run deploy.ts

Obtaining Selectors

At this stage, you need to obtain the function selectors corresponding to the facet signatures. This guide outlines two approaches you can use to generate these selectors.

Approach 1: Manual Conversion

For this approach, you need to use the signature-to-selector converter, which allows generating a valid selector for a given signature.

Use the data table provided in this topic to refer to the corresponding smart contract documentation for function signatures.

For each facet, you need to create the corresponding array where you will store selectors. For demonstration purposes, only two selector arrays are provided below:

const AccessControlFacetSelectors = [
    "0x91d14854"
]
 
const StateFacetSelectors = [
    "0xcc90cf94",
    "0x06a91c6a"
]

Approach 2: Automatic Conversion

This approach relies on the automatic generation of selectors based on the human-readable-abi standard.

For all function signatures, refer to the corresponding facet documentation that you can access through the data table provided in this topic.

Create arrays that will store the function signatures. For demonstration purposes, only two signature arrays are provided below:

const AccessControlFacetAbi = [
    "function hasRole(bytes32 role, address account) external view returns (bool)"
]
 
const StateFacetSelectorsAbi = [
    "function changeState(uint256 campaignId, uint256 fromState, uint256 toState) external",
    "function getStateOfId(uint256 campaignId) external view returns (uint256)"
]

Then you have to use the functionality of the ethers library to iterate through all signatures in the arrays and convert them into selectors. Ensure that you replace the value passed to the Interface instance.

import { Interface, id, FunctionFragment, hashMessage, dataLength } from "ethers";
 
//  Create an Interface
const iface = new Interface(StateFacetSelectorsAbi);
 
// Loop over all function signatures
let StateFacetSelectorsAbiResult = []
 
for (const fragment of iface.fragments) {
  if (fragment.type === "function") {
    const fnFragment = fragment as FunctionFragment;
    const signature = fnFragment.format(); // canonical signature
    const selector = id(signature).slice(0, 10); // 4-byte selector
    console.log(`${selector}`);
    StateFacetSelectorsAbiResult.push(selector);
  }
}

Adding Facets To Diamond Proxy

Next, you have to create an array of FacetCut objects containing the function selectors that will be added to the diamond proxy. In the Solidity code, the FacetCut is represented as the following struct:

struct FacetCut {
  address target;
  FacetCutAction action;
  bytes4[] selectors;
}

The FacetCutAction represents an enum that determines how to handle the facet cut process. In our case, we need to use the ADD member of the enum, which is represented by the index position 0:

enum FacetCutAction {
 ADD,
 REPLACE,
 REMOVE
}

You need to specify the address of the facet, the FacetCutAction member, which is 0, and an array of selectors for each facet that you want to add to the diamond proxy.

const AccessControlFacetAddress = "0xFd01Dd59308F9Ca6266d885f7DcED7520230074A"
const StateFacetAddress = "0x5bef016eA1e5DA7b3B8741FfcE70f7E907c174BF"
 
let facet1 = { target: AccessControlFacetAddress, action: 0, selectors: AccessControlFacetSelectors}
let facet2 = { target: StateFacetAddress, action: 0, selectors: StateFacetSelectors}

Now we have prepared all the required FacetCut objects, and we are ready to add them to the diamond proxy.

Next, you need to create an instance of the diamond proxy you just deployed:

const diamondProxyContract = new ethers.Contract(diamondAddress, abi, wallet);

We also need to define an async operation to execute the diamondCut function on the instance of the diamond proxy smart contract.

async function diamondCut() {
  const result = await diamondProxyContract.diamondCut([facet1, facet2], ethers.ZeroAddress, "0x");
  console.log(result)
}

As you can see, the first argument expects an array of facet arrays containing selectors; the second argument expects the zero address, which we pass using ethers.ZeroAddress; while the third argument expects the init data, which is empty ("0x").

Now you can call the diamondCut() function, which will return the result of the operation:

diamondCut()

After adding the facets to the diamond proxy, you can verify their presence by using the Louper web tool.
Insert the diamond proxy address into the search bar and verify the newly added functions.

Diamond Proxy Storage Initialization

After adding facets to the diamond proxy, we need to initialize them.

Create instances of the facets that need initialization. These instances must be called at the address of the diamond proxy in order to interact with them through the diamond proxy:

const facet1AtDiamond = new ethers.Contract(diamondAddress, iface, wallet);

Define the async function to call initAccessControlFacet on the facet contract:

async function initializeFacet() {
  const result = await facet1AtDiamond.initAccessControlFacet(wallet.address);
  console.log(result)
}

Now, by calling the initializeFacet function, you initialize the diamond storage for the selected facet. In case you have added more facets to your diamond contract, you need to initialize them too.

initializeFacet()

If you need to pass any other data, you have to encode it properly. For instance, this guide requires initializing the TwoBorderTimeFacet by calling the initPurchaseTimeFacet() function with the initPurchaseTimeData calldata. To obtain the data, you need to refer to the corresponding FacetStorage smart contract - which in this case is: TwoBorderTimeFacetStorage.

After that, you need to find the initPurchaseTimeData parameter in the table provided in the Reference.

Finally, you have to encode the data properly by using the following function:

ethers.utils.defaultAbiCoder.encode(["bytes"], ["YOUR_DATA_IS_HERE"]);

Interacting with the Fraction Platform

Suppose you need to interact with the platform we've set up—specifically, to get the state of a specific campaign. First, obtain an instance of the facet that provides the required functionality (i.e., getStateOfId()) at the diamond proxy address:

const StateFacetFacetAbi = [
    "function getStateOfId(uint256 campaignId) external view returns (uint256)"
]
let StateFacetAtDiamond = new ethers.Contract(diamondAddress, StateFacetFacetAbi, wallet);

Then you will call the function from this instance:

let campaignId = 1;
 
async function getStateOfId() {
  const result = await StateFacetAtDiamond.getStateOfId(campaignId);
  console.log(result);
}