Monax Help Center

Monax Help Center

Integrating with the agreements beacon

Intro

Nomenclature

  • beacon (or agreements beacon): the smart contract that powers actions within the the Monax Digital Agreement platform
  • legalURI: the off chain location which is similar to, but more structured than, the tokenURI often used by various blockchain tokens
  • beaconCreator: this is the address who has the capability of turning on a beacon or updating it
  • templateCreator: this is the user/organization on Monax that creates a template that has also been authorized to be used from a given foreign chain

Background

Each beacon that a DApp (or App) connects into has a function called getBeaconURI. It will return a templated URI representing the off chain location where it serves a set of defined data to the public. The resolved location of the templated URI (which may use one or both of the following variables {tokenContractAddress} and/or {tokenId}) will return a human readable html page with information regarding the token. The beaconURI is also known in this document as the legalURI, when a beacon has been activated for a given token the legalURI will serve additional information beyond the human readable html page including:

  • tokenLegalData which is a set of information that can be consumed by machine readable systems. Part of the tokenLegalData is fixed and was populated by the beacon creator when they created or updated their beacon. Part of the tokenLegalData includes meta-information such as the termsIPFSHash and the dataIPFSHash. It also includes the various transactions that make up the history of the agreements which relate to the token. It can be found at legalURI/data
  • tokenTerms is a document in (pdf|html|svg format) that can be consumed by almost any front end system. It can be found at legalURI/terms

How to integrate with the agreements beacon

There are 3 “areas” (one of which is optional) in which platform operators can leverage the agreements beacon. The more of these areas that are implemented by more platforms the greater the benefit to creators and collectors. That said, a gradual approach to implementation has been purposefully designed. Allowing you to start small and grow over time as more (or less) of your users need rights defined outside of the solidity layer.

Area 1: Connect the tokenTerms and requestCreateAgreement workflow into your buying system

tokenTerms is a single (pdf|html|svg) document served at a well known URI easily accessible from wherever your users are. It should be as easy as:

<object data="{tokenMetadata.legal}/terms" width="100%" height="800px"></object>

This can then be shown at any point within your buying sequence which is optimized for your DApp (App) community (users). (You can also view the terms via the metadata.termsIPFSHash which is available from the tokenLegalData (served at {tokenMetadata.legal}/data). To create an agreement from the template registered with the beacon, only one simple transaction is needed:

const agreement = await beacon721.requestCreateAgreement(tokenContract.address, tokenId, [...buyersAddresses], {
  value: await beacon721.AGREEMENT_BEACON_PRICE(),
});
await agreement.wait();

or

const agreement = await beacon1155.requestCreateAgreement(tokenContract.address, [...tokenIds], buyerAddress, {
  value: await beacon1155.AGREEMENT_BEACON_PRICE(),
});
await agreement.wait();

Beacons will exist on various chains and will have ABIs registered with Etherscan and Sourcify.

Area 2: Connect the legalURI and requestCreateBeacon workflow via your minting system

The legalURI is best placed to being added as the legal field of the JSON that serves as the token’s metadata from the tokenURI location. To then turn on a beacon during the minting process send one transaction to bundle up for your users:

const activation = await beacon.requestCreateBeacon(tokenContract.address, tokenId, formatBytes32String(templateId), templateConfigIPFSHash, {
  value: await beacon.AGREEMENT_BEACON_PRICE(),
});
await activation.wait();

N.B. - some assembly is required in Area 4. Namely the need to work with your community // users // management team // legal team to come up with a suitable digital agreement template and work to have that team authorize one or more templates to be used by a given creator OR a given token contract address.

Area 4 (optional): Connect the beacon into your preTransferHooks

One quick solidity require:

require(
    _agreementsBeacon.getAgreementStatus(
        address(this),
        tokenId,
        to
    ) >= IAgreementsBeacon.LegalState.FORMULATED,
    "please agree to the terms first"
);

Now creators have the certainty that work they mint will need to have its then current terms agreed to before the solidity allows possession to change.

How to provide services into this ecosystem

Area 1: Produce templates.

Area 2: Audit//assurance.

Ready to get started?

Drop your email to receive updates.