Referrals

All referrers have to be approved by LandWorks in order to be eligible to refer. Please contact the LandWorks team through various communication channels in order to discuss referral opportunities.

Applications, which would like to refer users to list or rent assets in LandWorks. Referring someone upon list or rent gives you a fixed percentage of the rent protocol fees on every referred action.

Apart from executing contracts function to list or rent in LandWorks, we think it will be helpful to use LandWorks' Subgraph implementation, currently deployed here, which provides a quicker approach on fetching everything related to LandWorks, rather than doing view calls to the contract.

Listing Assets

Currently, only a set of Metaverse registries (ERC-721) can be listed for rent on LandWorks. Each listed property accepts an approved payment token (ERC-20) / ETH as a rent payment.

Below are the queries needed to display all available metaverse registries and payment tokens.

Querying supported Metaverse registries

gql`
  # Queries all Metaverse available, including their metaverse registries 
  query GetMetaverses {
    metaverses {
      # The ID of the metaverse
      id
      # The name of the metaverse
      name
      # An array of the metaverse's registries
      registries {
        # The address of the Metaverse registry
        id
        # The symbol of the Metaverse registry
        symbol
        # The name of the Metaverse registry
        name
      }
    }
  }
`

or you can directly query the Metaverse registries:

gql`
  # Queries all Metaverse Registries in LandWorks
  query GetMetaverseRegistries {
    metaverseRegistries {
      # The address of the metaverse registry
      id
      # The symbol of the metaverse registry
      symbol
      # The name of the metaverse registry
      name
      metaverse {
        # The ID of the metaverse
        id
        # The name of the Metaverse to which the registry belongs
        name
      }
    }
  }
`

Querying supported Payment Tokens

gql`
  # Queries all accepted payment tokens for rents in LandWorks
  query GetPaymentTokens {
    paymentTokens {
      # The address of the payment token (`0x0000000000000000000000000000000000000001` for ETH)
      id
      # The symbol of the payment token
      symbol
      # The name of the payment token
      name
      # The payment token's decimals
      decimals
      # The fee percentage, which will be deducted from the rent fee as protocol fee. Maximum percentage is 100_000. (e.g. 3_000 =>3 %)
      feePercentage
    }
  }
`

Populating the necessary information

Once the token ID from the given Metaverse registry (ERC-721) has been selected, user must choose the rent properties, which include:

  • minPeriod

  • maxPeriod

  • maxFutureTime

  • paymentToken

  • pricePerSecond

More information here.

Approving LandWorks

After the properties have been chosen, user must approve LandWorks to be able to operate with the selected token ID or with the whole collection.

await metaverseRegistry.approve(landWorksAddress, tokenID);

or

await metaverseRegistry.setApprovalForAll(landWorksAddress, true);

Listing the asset

Once LandWorks is approved on user's behalf, execute:

    /// @notice Provides asset of the given metaverse registry for rental.
    /// Transfers and locks the provided metaverse asset to the contract.
    /// and mints an asset, representing the locked asset.
    /// Listing with a referrer might lead to additional rewards upon rents.
    /// Additional reward may vary depending on the referrer's requested portion for listers.
    /// If the referrer is blacklisted after the listing,
    /// listers will not receive additional rewards.
    /// See {IReferralFacet-setMetaverseRegistryReferrers}, {IReferralFacet-setReferrers}.
    /// @param _metaverseId The id of the metaverse
    /// @param _metaverseRegistry The registry of the metaverse
    /// @param _metaverseAssetId The id from the metaverse registry
    /// @param _minPeriod The minimum number of time (in seconds) the asset can be rented
    /// @param _maxPeriod The maximum number of time (in seconds) the asset can be rented
    /// @param _maxFutureTime The timestamp delta after which the protocol will not allow
    /// the asset to be rented at an any given moment.
    /// @param _paymentToken The token which will be accepted as a form of payment.
    /// Provide 0x0000000000000000000000000000000000000001 for ETH.
    /// @param _pricePerSecond The price for rental per second
    /// @param _referrer The target referrer
    /// @return The newly created asset id.
    function list(
        uint256 _metaverseId,
        address _metaverseRegistry,
        uint256 _metaverseAssetId,
        uint256 _minPeriod,
        uint256 _maxPeriod,
        uint256 _maxFutureTime,
        address _paymentToken,
        uint256 _pricePerSecond,
        address _referrer
    ) external returns (uint256);
Name
Description

_referrer

The addresses of the referrer. All referrers have to be approved by LandWorks before being eligible to refer.

Renting Assets

To display the currently available assets for rent, you can use LandWorks' Subgraph implementation.

Querying all currently listed assets

gql`
  # This query fetches the currently listed assets in LandWorks
  query getListedAssets {
    assets(where:{status:LISTED}) {
      # The asset's id
      id
      metaverse {
        # The name of the metaverse
        name
      }
      # The asset's metaverse registry (LAND, Estate, Voxels, etc.)
      metaverseRegistry { 
        # The address of the metaverse registry
        id
        # The symbol of the metaverse registry
        symbol
        # The name of the metaverse registry
        name
      }
      # The asset's metaverse asset id
      metaverseAssetId
      # The minimum period (in seconds) that the asset can be rented
      minPeriod
      # The maximum period (in seconds) that the asset can be rented
      maxPeriod
      # The timestmap delta after which the protocol will not allow the asset to be rented at any given moment
      maxFutureTime
      # The payment token that is currently accepted as rent payment 
      paymentToken {
        # The address of the payment token (`0x0000000000000000000000000000000000000001` for ETH)
        id
        # The symbol of the payment token
        symbol
        # The name of the payment token
        name
        # The payment token's decimals
        decimals
        # The fee percentage, which will be deducted from the rent fee as protocol fee. Maximum percentage is 100_000. (e.g. 3_000 =>3 %)
        feePercentage
      }
      # The price for 1 (one) second rent in paymentToken (lowest denomination)
      pricePerSecond
      # When the last rent (in epoch timestamp) has expired/will expired. 
      # If the last rent has expired, the next rent will begin when the rent transaction is successfully mined
      # Can be used to visualise when the next rent will begin at
      lastRentEnd
      # The status of the asset (LISTED, DELISTED, WITHDRAWN)
      status
      # The total amount of rents for the given asset
      totalRents
    }
  }
`

Example output

{
  "data": {
    "assets": [
      {
        "id": "101",
        "metaverse": {
          "name": "Decentraland"
        },
        "metaverseRegistry": {
          "id": "0x959e104e1a4db6317fa58f8295f586e1a978c297",
          "symbol": "EST",
          "name": "Estate"
        },
        "metaverseAssetId": "3076",
        "minPeriod": "604800",
        "maxPeriod": "2592000",
        "maxFutureTime": "7776000",
        "paymentToken": {
          "id": "0x0000000000000000000000000000000000000001",
          "symbol": "ETH",
          "name": "Ether",
          "decimals": 18,
          "feePercentage": "3000"
        },
        "pricePerSecond": "231481481481",
        "lastRentEnd": "1653895143",
        "status": "LISTED",
        "totalRents": "1"
      },
      {
        "id": "98",
        "metaverse": {
          "name": "Voxels"
        },
        "metaverseRegistry": {
          "id": "0x79986af15539de2db9a5086382daeda917a9cf0c",
          "symbol": "CVPA",
          "name": "Cryptovoxels Parcel"
        },
        "metaverseAssetId": "1225",
        "minPeriod": "86400",
        "maxPeriod": "12960000",
        "maxFutureTime": "12960000",
        "paymentToken": {
          "id": "0x0000000000000000000000000000000000000001",
          "symbol": "ETH",
          "name": "Ether",
          "decimals": 18,
          "feePercentage": "3000"
        },
        "pricePerSecond": "77546296296",
        "lastRentEnd": "1664546820",
        "status": "LISTED",
        "totalRents": "2"
      }
    ]
  }
}

Explanation

  • The data returned is an array of two elements:

    • The first asset is Asset #101, which represents Decentraland Estate #3076, which:

      • has minimum rent period of 1 week (604800)

      • has maximum rent period of 1 month (2592000)

      • has maximum future time of 3 months (7776000)

      • accepts ETH as rent payment, which has a 3% protocol fee from the rent price

      • has a rent fee of 0.02 ETH/day =>

        • (pricePerSecond * seconds in a day) / (10 ** token decimals)

        • (231481481481 * 86400) / (10 ** 18)

      • next rent will begin immediately after the rent transaction has been successfully mined, because the last rent (1653895143) has ended in the past.(lastRentEnd < now)

      • has 1 total rents

    • The second asset is Asset #98, which represents Voxels Parcel #1225, which:

      • has minimum rent period of 1 day (86400)

      • has maximum rent period of 5 months (12960000)

      • has maximum future time of 5 months (12960000)

      • accepts ETH as rent payment, which has a 3% protocol fee from the rent price

      • has a rent fee of 0.0067 ETH/day

      • next rent will begin after 17:07 30.09.2022 (1664546820)

      • has 2 total rents

Renting the Asset

Once the user has selected an asset and the duration for the given rent, interact with LandWorks contract with a view function, which will calculate the total rent fee, based on asset, duration period and referrer:

/// @notice Returns an asset rent fee based on period and referrer
/// Calculates the rent fee based on asset, period and referrer.
/// A rent fee discount might appear depending on referral
/// percentages.
/// @dev Reverts if the _referrer is not whitelisted.
/// Portions of the protocol fee might be given as discount depending
/// referrals. Priority is the following:
/// 1. Metaverse registry referrer: If the given asset metaverse registry has a metaverse
/// referrer, it accrues a percent of the protocol fees to that referrer.
/// 2. Rent referrer: Takes percentage from (protocol fees - metaverse registry fee) based on `mainPercentage`.
/// `mainPercentage` has a maximum percentage of 50 due to list referrer.
/// The renter itself might take percentage of the rent referral based on `secondaryPerceange`,
/// which will serve as discount to the initial rent amount.
/// @param _assetId The target asset
/// @param _period The target rental period (in seconds)
/// @param _referrer The address of the referrer
/// @return paymentToken_ The target payment token
/// @return amount_ The amount that has to be paid
function calculateRentFee(
    uint256 _assetId,
    uint256 _period,
    address _referrer
) external view returns (address paymentToken_, uint256 amount_);

This will return the rent fee that the user has to provide upon rent execution.

_assetId

The target asset id

_period

The rent period in seconds.

_referrer

The addresses of the referrer. All referrers have to be approved by LandWorks before being eligible to refer.

Once an asset has been selected, execute the following rent function:

  • Decentraland - rentDecentraland

/// @notice Rients Decentraland Estate/LAND.
/// @param _assetId The target asset
/// @param _period The target period of the rental
/// @param _maxRentStart The maximum rent start allowed for the given rent
/// @param _operator The target operator, which will be set as operator once the rent is active
/// @param _paymentToken The current payment token for the asset
/// @param _amount The target amount to be paid for the rent
/// @param _referrer The target referrer
function rentDecentraland(
    uint256 _assetId,
    uint256 _period,
    uint256 _maxRentStart,
    address _operator,
    address _paymentToken,
    uint256 _amount,
    address _referrer
) external payable;

  • Other Metaverse registries - rentWithConsumer

/// @notice Rents an asset, providing a consumer that will consume the asset
/// during its rental period.
/// @dev The asset's metaverse must have previously set a metaverse consumable adapter.
/// @dev If there are no active rents, this rent will begin, which will set
/// the consumer directly in the metaverse consumable adapter.
/// If there are any active or upcoming rents, when this rent's time comes,
/// {IMetaverseConsumableAdapterFacet-updateAdapterState} must be called
/// in order to set the consumer in the metaverse consumable adapter.
/// @param _assetId The target asset
/// @param _period The target period of the rental
/// @param _maxRentStart The maximum rent start allowed for the given rent
/// @param _consumer The target consumer, which will be set as consumer in the
/// consumable adapter once the rent is active
/// @param _paymentToken The current payment token for the asset
/// @param _amount The target amount to be paid for the rent
/// @param _referrer The target referrer
function rentWithConsumer(
    uint256 _assetId,
    uint256 _period,
    uint256 _maxRentStart,
    address _consumer,
    address _paymentToken,
    uint256 _amount,
    address _referrer
) external payable;
Name
Description

_assetId

The selected asset id

_period

The target period of the rental

_maxRentStart

The maximum rent start allowed for the given rent. This is used to prevent potential front-running of rents. Provide a timestamp number in the future (e.g. 1 hour ahead of now()

_operator/_consumer

The address, which will be set as operator/consumer to the Metaverse Registry

_paymentToken

The asset's payment token address

_amount

The fee amount returned from calculateRentFee

_referrer

The address of the referrer. All referrers have to be approved by LandWorks before being eligible to refer.

Additional links

PreviousOwnershipNextDecentraland

Last updated