LandWorks Widget

Be able to list and rent from everywhere!

Installation

npm install @enterdao/landworks-widget --save

Example

import {
  ListingModal,
  RentingModal,
  WidgetTheme,
} from "@enterdao/landworks-widget/dist/main";

const mintTheme: WidgetTheme = {
  colors: {
    primary: '#5cdb95',
    primaryContrastText: '#fff',
    background: '#05385b',
    error: '#f35588',
    success: '#5cdb95',
    textPrimary: '#edf5e1',
    textSecondary: '#348aa2',
    textDisabled: '#20688a',
    infoAlertBackground: '#114761'
  },
  button: {
    minHeight: 48
  }
}

const App = () => {
  const [isListingModalOpened, setIsListingModalOpened] = useState(false);
  const [isRentingModalOpened, setIsRentingModalOpened] = useState(false);

  const provider = useMemo(() => {
    if (window?.ethereum && window?.ethereum.providers?.length) {
      return window?.ethereum.providers.find((p: any) => p.isMetaMask);
    }

    return window?.ethereum;
  }, []);

  const handleSuccess = (transactionReceipt: any) => {
    console.log(transactionReceipt);

    setIsListingModalOpened(false);
    setIsRentingModalOpened(false);
  };

  const handleError = (e: Error) => {
    console.log(e);
  };

  return (
    <>
      <button onClick={() => setIsListingModalOpened(true)}>List</button>
      <button onClick={() => setIsRentingModalOpened(true)}>Rent</button>

      <ListingModal
        provider={provider}
        open={isListingModalOpened}
        onClose={() => setIsListingModalOpened(false)}
        onSuccess={handleSuccess}
        onError={handleError}
        tokenAddress="0x7a7f6c8a0715fb34e92c31985b98c9ef833044f8"
        referrer="0x0000000000000000000000000000000000000000"
        tokenId="3"
        theme={mintTheme}
      />

      <RendingModal
        provider={provider}
        open={isRentingModalOpened}
        onClose={() => setIsRentingModalOpened(false)}
        onSuccess={handleSuccess}
        onError={handleError}
        referrer="0x0000000000000000000000000000000000000000"
        assetId="9"
        theme={mintTheme}
      />
    </>
  );
};

What can cause modals to show an error?

To guarantee that passed data in listing/renting modal is correct and not altered, modal can show user an error.

Here are the cases that can cause an error:

• If provider, tokenId, assetId, tokenAddress or referrer changes when listing/renting modal is open;
• If the referrer is incorrect or not whitelisted (can by fixed by specifying a valid referrer provided by the LandWorks or use 0x0000000000000000000000000000000000000000);
• If for the renting modal you provided asset with id assetId that doesn't exist or asset with id assetId is delisted/withdrawn by the owner;
• If for the listing modal you provided tokenAddress that is invalid or it's not one the listed here;
• If for the listing modal you provided token with id tokenId that active wallet doesn't have or token doesn't belong to metaverse registry with address tokenAddress.

To prevent errors, make sure you are passing correct data and don't alter the data when modal is open.

Props

Common props:

| Prop | Type | Default | Description | |-------------------------|------------|-------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | open | boolean | required | Triggering the opening of the modal. | | onClose | function | undefined | Callback function, called upon modal closing. Triggered when user clicks outside of the modal or clicks on close | | onError | function | undefined | Callback function, called upon error. | | onSuccess | function | undefined | Callback function, called after contract execution (transaction) has been mined. | | provider | object | required | Web3 provider. | | referrer | string | required | EVM wallet address, passed as referrer upon listing and renting. Specify 0x0000000000000000000000000000000000000000 if you do not want to use a referrer. Ping us to get a referrer! | | theme | object | undefined | Object, used for changing look of the widget |

Listing modal props:

| Prop | Type | Default | Description | |-------------------------------|----------|------------|------------------------------------------------------------------------------------| | tokenAddress | string | required | Address of the ERC-721 collection. | | tokenId | string | required | Token ID from the ERC-721 collection. Provider address must have it in its wallet. |

Renting modal props

| Prop | Type | Default | Description | |---------|----------|------------|-----------------------------------------------| | assetId | string | required | The LandWorks Asset ID that you want to rent. |

onError

Callback, with first parameter as an error, that will be triggered in the following cases:

• When user rejects transaction or something unexpected happens during the transaction.
• When user rejects approval or something unexpected happens during the approval.

onSuccess

When listing or renting was successful callback will be triggered with transaction receipt as first parameter.

Structure of the transaction receipt:

interface TransactionReceipt {
  status: boolean;
  transactionHash: string;
  transactionIndex: number;
  blockHash: string;
  blockNumber: number;
  from: string;
  to: string;
  contractAddress?: string;
  cumulativeGasUsed: number;
  gasUsed: number;
  effectiveGasPrice: number;
  logs: Log[];
  logsBloom: string;
  events?: {
    [eventName: string]: EventLog;
  };
}

provider

Web3 provider that used by your app.

Currently widget supports next providers:

• MetaMask
• WalletConnect
• Coinbase

referrer

Used by 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.

theme

Allows you to customize the look of the widget to match the design of your web app.

To customize the widget you can tweak some of the following options:

interface WidgetTheme {
  colors?: WidgetThemeColors;
  zIndex?: number;
  typography?: TypographyOptions;
  components?: WidgetThemeComponents;
  borderRadius?: WidgetThemeBorderRadius;
}

colors

Colors of the widget.

Optional properties are calculated based on required properties.

interface WidgetThemeColors {
  primary: string;
  primaryContrastText: string;

  success: string;
  error: string;

  textPrimary: string;
  textSecondary: string;
  textDisabled: string;

  background: string; // Background of the modal

  link?: string; // Link color

  paper?: string;

  backgroundDivider?: string;
  paperDivider?: string;

  actionDisabledText?: string; // Text of the disabled element e.g. button
  actionDisabledBackground?: string; // Background of the disabled e.g. button

  actionHoverOverlay?: string; // Color of the overlay that appear when hovered over action elements e.g. button
  actionSelectedOverlay?: string; // Color of the overlay that appear when element is selected e.g. option of the select component

  loaderBackground?: string;
  loaderForeground?: string;

  tooltipTitle?: string;
  tooltipText?: string;
  tooltipBackground?: string;

  infoAlertIcon?: string;
  infoAlertBackground?: string;
  infoAlertText?: string;
  infoAlertTitle?: string;

  modalCloseButtonBackground?: string;
  modalCloseButtonForeground?: string;

  inputFocusBorder?: string; // Border color of the focused input
  inputBackground?: string;

  accentButtonText?: string;
  accentButtonBackground?: string;
  accentButtonGradient?: string;
}

zIndex

z-index of the modal. Also used to calculate z-index of the tooltip.

typography

Object for changing typography of the widget. Has the same structure like mui's theme typography property with additional link variant.

components

Object that used for customizing some of the components of the widget.

Values of component object are style objects that are the same as the ones that used for the styled utility of the mui.

interface WidgetThemeComponents {
  dialog?: CSSObject; // Widgets modal dialog
  backdrop?: CSSObject; // Backdrop of the modal
  input?: CSSObject;
  paper?: CSSObject;
  alert?: CSSObject;
  button?: CSSObject; // Common styles of the button
  defaultButton?: CSSObject;
  accentButton?: CSSObject;
  listingModalSummaryCard?: CSSObject;
  rentingModalDetailsCard?: CSSObject;
  rentingModalSummaryCard?: CSSObject;
}

borderRadius

Border radiuses used in the widget.

interface WidgetThemeBorderRadius {
  md: string;
  lg: string;
  xl: string;
}

Default value:

{
  md: "10px",
  lg: "15px",
  xl: "20px"
}

tokenAddress

ERC-721 collection address also known as metaverse registry address.

Each metaverse has their own metaverse registry address. Also some different types of tokens can have different registry addresses.

Currently LandWorks has next metaverse registry addresses:

• Decentraland:
  • For Lands: 0xf87e31492faf9a91b02ee0deaad50d51d56d5d4d
  • For Estates: 0x959e104e1a4db6317fa58f8295f586e1a978c297
• Voxels: 0x79986af15539de2db9a5086382daeda917a9cf0c