Marketplace Contract Technical Reference

This is a technical reference for the Media Protocol's Marketplace smart contract.

Inheritance

The Marketplace contract inherits Recoverable, and Open Zeppelin's ReentrancyGuard contracts.

Structs

Provider

struct Provider {
    string metadata;
    string publicKey;
}

Name	Type
metadata	string	Metadata for the provider.
publicKey	string	The encryption public key shared to the clients to encrypt their resources.

---

OfferTerms

struct OfferTerms {
    uint pricePerSecond;
    uint minDealDuration;
    bool billFullPeriods;
    bool singlePeriodOnly;
    string metadata;
}

Name	Type
pricePerSecond	uint	Price per second for the deals.
minDealDuration	uint	The minimum duration that deal's must have, expressed in seconds.
billFullPeriods	bool	If enabled, once the minimum deal's duration has elapsed the next billing will cover a complete billing period up to the minimum duration.
singlePeriodOnly	bool	If enabled, only one period will be billed and then the deal will be considered finished. (Can't extend for more periods)
metadata	string	Useful additional information about the offer.

---

Offer

struct Offer {
    uint id;
    address provider;
    string publicKey;
    uint maximumDeals;
    bool autoAccept;
    OfferTerms terms;
}

Name	Type
id	uint	The id of the offer.
provider	address	The address of the provider.
publicKey	string	The encryption public key shared to the clients to encrypt their resources.
maximumDeals	uint	The maximum amount of deals that this offer can provide.
autoAccept	bool	Defines whether the offer will auto-accept deals or not.
terms	OfferTerms	The terms of the offer.

---

Deal

struct Deal {
    uint id;
    uint offerId;
    address client;
    address provider;
    uint resourceId;
    uint totalPayment;
    uint blockedBalance;
    OfferTerms terms;
    Status status;
}

Name	Type
id	uint	The id of the deal.
offerId	uint	The id of the offer.
client	address	The address of the client.
provider	address	The address of the provider.
resourceId	uint	The id of the resource.
totalPayment	uint	The total payment for the deal.
blockedBalance	uint	The amount of tokens blocked for the deal.
terms	OfferTerms	The terms of the deal.
status	Status	The status of the deal.

---

Status

struct Status {
    bool active;
    uint createdAt;
    uint acceptedAt;
    uint billingStart;
    bool cancelled;
    uint cancelledAt;
}

Name	Type
active	bool	Whether the deal is active or not.
createdAt	uint	The timestamp when the deal was created.
acceptedAt	uint	The timestamp when the deal was accepted.
billingStart	uint	The timestamp when the billing started.
cancelled	bool	Whether the deal was cancelled or not.
cancelledAt	uint	The timestamp when the deal was cancelled.

---

Public State Variables

General Variables

Name	Type
positionManager	IUniswapV3PositionManager	Uniswap V3 position manager.

Marketplaces Variables

The following variables are mappings that store the data specific to each marketplaceId.

Name	Type
offerCounter	mapping(uint => uint)	Mapping of offer counters.
offerAutoIncrement	mapping(uint => uint)	Mapping of offer auto-increments.
dealAutoIncrement	mapping(uint => uint)	Mapping of deal auto-increments.

Write Functions

registerProvider

Registers as provider in order to be able to create offers.

function registerProvider(
    uint marketplaceId,
    string calldata metadata,
    string calldata publicKey,
    uint nftId
) external nonReentrant onlyAuthorized returns (bool);

Parameters:

Name	Type
marketplaceId	uint	The id of the marketplace you are registering to.
metadata	string	Metadata for the provider.
publicKey	string	The encryption public key shared to the clients to encrypt their resources.
nftId	uint	The Uniswap V3 NFT ID with the required liquidity.

Return values:

Type
bool	Whether the registration was successful or not.

---

unregisterProvider

Unregister as a provider and recover the staked lp tokens.

function unregisterProvider(
    uint marketplaceId
) external nonReentrant onlyAuthorized returns(uint nftId);

Parameters:

Name	Type
marketplaceId	uint	The id of the marketplace where you are registered.

Return values:

Name	Type
nftId	uint	The unstaked Uniswap V3 NFT ID with the liquidity.

---

updateProvider

Updates the provider's information.

function updateProvider(
    uint marketplaceId,
    string calldata metadata,
    string calldata publicKey
) external onlyAuthorized nonReentrant returns (bool updated);

Parameters:

Name	Type
marketplaceId	uint	The id of the marketplace where you are registered.
metadata	string	The new metadata for the provider.
publicKey	string	The new encryption public key

Return values:

Name	Type
updated	bool	Whether the update was successful or not.

---

increaseProviderStake

Increases the provider's stake.

function increaseProviderStake(
    uint marketplaceId,
    uint liquidity,
    uint amount0,
    uint amount1
) external nonReentrant onlyAuthorized returns (bool);

Parameters:

Name	Type
marketplaceId	uint	The id of the marketplace where you are registered.
liquidity	uint	The amount of liquidity to increase.
amount0	uint	The amount of token0 to increase.
amount1	uint	The amount of token1 to increase.

Return values:

Type
bool	Whether the increase was successful or not.

---

decreaseProviderStake

Decreases the provider's stake.

function decreaseProviderStake(
    uint marketplaceId,
    uint amount0,
    uint amount1
) external nonReentrant onlyAuthorized returns (bool);

Parameters:

Name	Type
marketplaceId	uint	The id of the marketplace where you are registered.
amount0	uint	The amount of token0 to decrease.
amount1	uint	The amount of token1 to decrease.

Return values:

Type
bool	Whether the decrease was successful or not.

---

createOffer

Creates a new offer.

function createOffer(
    uint marketplaceId,
    uint maximumDeals, 
    bool autoAccept, 
    uint pricePerSecond, 
    uint minDealDuration,
    bool billFullPeriods,
    bool singlePeriodOnly,
    string calldata metadata
) external nonReentrant returns (uint offerId);

Parameters:

Name	Type
marketplaceId	uint	The id of the marketplace where you are registered.
maximumDeals	uint	The maximum amount of deals that this offer can provide.
autoAccept	bool	Defines whether the offer will auto-accept deals or not.
pricePerSecond	uint	Price per second for the deals.
minDealDuration	uint	The minimum duration that deal's must have, expressed in seconds.
billFullPeriods	bool	If enabled, once the minimum deal's duration has elapsed the next billing will cover a complete billing period up to the minimum duration.
singlePeriodOnly	uint	If enabled, only one period will be billed and then the deal will be considered finished. (Can't extend for more periods)
metadata	string	Useful additional information about the offer.

Return values:

Name	Type
offerId	uint	The id of the created offer.

---

updateOffer

Updates an offer. It is important to clarify that once a Deal is taken, it cannot be modified. If you modify a offer with opened deals, only new Deals will follow the updated Offer parameters.

function updateOffer(
    uint marketplaceId,
    uint offerId, 
    uint maximumDeals, 
    bool autoAccept, 
    uint pricePerSecond, 
    uint minDealDuration,
    bool billFullPeriods,
    bool singlePeriodOnly,
    string calldata metadata
) external nonReentrant (bool);

Parameters:

Name	Type
marketplaceId	uint	The id of the marketplace where you are registered.
offerId	uint	The id of the offer you want to update.
maximumDeals	uint	The maximum amount of deals that this offer can provide.
autoAccept	bool	Defines whether the offer will auto-accept deals or not.
pricePerSecond	uint	Price per second for the deals.
minDealDuration	uint	The minimum duration that deal's must have, expressed in seconds.
billFullPeriods	bool	If enabled, once the minimum deal's duration has elapsed the next billing will cover a complete billing period up to the minimum duration.
singlePeriodOnly	uint	If enabled, only one period will be billed and then the deal will be considered finished. (Can't extend for more periods)
metadata	string	Useful additional information about the offer.

Return values:

Type
bool	Whether the update was successful or not.

---

deleteOffer

Allows providers to delete their active offers.

function deleteOffer(
    uint marketplaceId, 
    uint offerId
) external nonReentrant returns (bool); 

Parameters:

Name	Type
marketplaceId	uint	The id of the marketplace where you are registered.
offerId	uint	The id of the offer you want to update.

Return values:

Type
bool	Whether the deletion was successful or not.

---

acceptDeal

Allows providers to accept a deal.

function acceptDeal(uint marketplaceId, uint dealId) external nonReentrant returns (bool);

Parameters:

Name	Type
marketplaceId	uint	The id of the marketplace where you are registered.
dealId	uint	The id of the deal you want to accept.

Return:

Type
bool	Whether the acceptance was successful or not.

---

rejectDeal

Allows providers to reject a deal.

function rejectDeal(uint marketplaceId, uint dealId) external nonReentrant returns (bool);

Parameters:

Name	Type
marketplaceId	uint	The id of the marketplace where you are registered.
dealId	uint	The id of the deal you want to reject.

Return:

Type
bool	Whether the rejection was successful or not.

---

createDeal

Allows a client to create a Deal from an Offer.

function createDeal(
    uint marketplaceId,
    uint resourceId,
    uint offerId,  
    uint blockedBalance,
    string calldata sharedKeyCopy
) external onlyAuthorized nonReentrant returns (
    uint dealId, 
    uint actualDeposit
);

Parameters:

Name	Type
marketplaceId	uint	The id of the marketplace where you are registered.
resourceId	uint	The id of the resource you want to create deals for.
offerId	uint	The id of the offer you want to create deals for.
blockedBalance	uint	The amount of tokens you want to block for the deal.
sharedKeyCopy	string	The encryption key for the deal.

Return values:

Name	Type
dealId	uint	The id of the created deal.
actualDeposit	uint	The amount of tokens blocked for the deal.

---

createDeals

Allow clients to create deals from an array of offers for a single resource.

function createDeals(
    uint marketplaceId,
    uint resourceId, 
    uint[] calldata offerIds, 
    uint[] calldata blockedBalance,
    string[] calldata _sharedKeyCopies
) external nonReentrant onlyAuthorized returns (uint[] memory dealsId, uint totalDeposit);

Parameters:

Name	Type
marketplaceId	uint	The id of the marketplace where you are registered.
resourceId	uint	The id of the resource you want to create deals for.
offerIds	uint[]	The ids of the offers you want to create deals for.
blockedBalance	uint[]	The amount of tokens you want to block for each deal.
_sharedKeyCopies	string[]	The encryption keys for each deal.

Return values:

Name	Type
dealsId	uint[]	The ids of the created deals.
totalDeposit	uint	The total amount of tokens blocked for the deals.

---

cancelDeal

Allows clients and providers to cancel a deal.

function cancelDeal(uint marketplaceId, uint dealId) external nonReentrant returns (bool);

Parameters:

Name	Type
marketplaceId	uint	The id of the marketplace where you are registered.
dealId	uint	The id of the deal you want to cancel.

Return:

Type
bool	Whether the cancellation was successful or not.

---

cancelAllDeals

Allows providers to cancel all their deals.

function cancelAllDeals(
    uint marketplaceId, 
    uint resourceId
) external nonReentrant returns (bool);

Parameters:

Name	Type
marketplaceId	uint	The id of the marketplace where you are registered.
resourceId	uint	The id of the resource you want to cancel deals for.

Return:

Type
bool	Whether the cancellation was successful or not.

---

addBalance

Allows clients to add balance to a deal.

function addBalance(
    uint marketplaceId, 
    uint dealId, 
    uint blockedBalance
) external nonReentrant returns (uint actualDeposit);

Parameters:

Name	Type
marketplaceId	uint	The id of the marketplace where you are registered.
dealId	uint	The id of the deal you want to add balance to.
blockedBalance	uint	The amount of tokens you want to add to the deal.

Return:

Name	Type
actualDeposit	uint	The amount of tokens that were actually deposited.

---

collectDeal

Allows clients and providers to collect a deal.

function collectDeal(
    uint marketplaceId, 
    uint dealId
) external nonReentrant returns (bool);

Parameters:

Name	Type
marketplaceId	uint	The id of the marketplace where you are registered.
dealId	uint	The id of the deal you want to collect.

Return:

Type
bool	Whether the collection was successful or not.

---

collectAllDeals

Allows providers to collect all their deals.

function collectAllDeals(uint marketplaceId) external nonReentrant returns (bool);

Parameters:

Name	Type
marketplaceId	uint	The id of the marketplace where you are registered.

Return:

Type
bool	Whether the collection was successful or not.

---

extendBillingStart

Allows providers to extend the billing start of a deal.

function extendBillingStart(
    uint marketplaceId, 
    uint dealId, 
    uint extension
) external nonReentrant returns (bool);

Parameters:

Name	Type
marketplaceId	uint	The id of the marketplace where you are registered.
dealId	uint	The id of the deal you want to extend.
extension	uint	The amount of time you want to extend the deal.

Return:

Type
bool	Whether the extension was successful or not.

---

Read Functions

hasActiveDeals

Returns whether an offer has active deals or not.

function hasActiveDeals(uint marketplaceId, uint offerId) public view returns (bool);

Parameters:

Name	Type
marketplaceId	uint	The id of the marketplace.
offerId	uint	The id of the offer.

Return:

Type
bool	Whether the offer has active deals or not.

---

isRegisteredProvider

Returns whether a provider is registered or not.

function isRegisteredProvider(
    uint marketplaceId, 
    address provider
) public view returns (bool);

Parameters:

Name	Type
marketplaceId	uint	The id of the marketplace.
provider	address	The address of the provider.

Return:

Type
bool	Whether the provider is registered or not.

---

getProvider

Returns the provider details.

function getProvider(uint marketplaceId, address provider) external view returns (Provider memory);

Parameters:

Name	Type
marketplaceId	uint	The id of the marketplace.
provider	address	The address of the provider.

Return:

Type
Provider memory	The provider details.

---

getOffer

Returns the details of an offer.

function getOffer(uint marketplaceId, uint offerId) external view returns (Offer memory);

Parameters:

Name	Type
marketplaceId	uint	The id of the marketplace.
offerId	uint	The id of the offer.

Return:

Type
Offer memory	The offer details.

---

getDeal

Returns the details of a deal.

function getDeal(uint marketplaceId, uint dealId) external view returns (Deal memory);

Parameters:

Name	Type
marketplaceId	uint	The id of the marketplace.
dealId	uint	The id of the deal.

Return:

Type
Deal memory	The deal details.

---

getProviderOffers

Returns a list of offers a provider has created.

function getProviderOffers(uint marketplaceId, address provider) external view returns (uint[] memory);

Parameters:

Name	Type
marketplaceId	uint	The id of the marketplace.
provider	address	The address of the provider.

Return:

Type
uint[] memory	An array of offer ids.

---

getOfferDealsIds

Returns a list of deal ids for an offer.

function getOfferDealsIds(uint marketplaceId, uint offerId) external view returns (uint[] memory);

Parameters:

Name	Type
marketplaceId	uint	The id of the marketplace.
offerId	uint	The id of the offer.

Return:

Type
uint[] memory	An array of deal ids.

---

getClientDeals

Returns a list of deals a client has created.

function getClientDeals(uint marketplaceId, address client) external view returns (uint[] memory);

Parameters:

Name	Type
marketplaceId	uint	The id of the marketplace.
client	address	The address of the client.

Return:

Type
uint[] memory	An array of deal ids.

---

getProviderDeals

Returns a list of deals a provider has created.

function getProviderDeals(uint marketplaceId, address provider) external view returns (uint[] memory);

Parameters:

Name	Type
marketplaceId	uint	The id of the marketplace.
provider	address	The address of the provider.

Return:

Type
uint[] memory	An array of deal ids.

---

getStakeAmount

Returns the amount of LP tokens a provider has staked.

function getStakeAmount(uint marketplaceId, address provider) public view returns (uint);

Parameters:

Name	Type
marketplaceId	uint	The id of the marketplace.
provider	address	The address of the provider.

Return:

Type
uint	The amount of LP tokens a provider has staked.

---

Events

Events are emitted for significant actions within the contract, such as registration of a provider, creation, acceptance, or cancellation of a deal. All event names and return values are self-descriptive.

• ProviderRegistered(uint _marketplaceId, address _provider)
• ProviderUpdated(uint _marketplaceId, address _provider)
• ProviderStakeDecreased(uint _marketplaceId, address _provider, uint _amount0, uint _amount1)
• ProviderStakeIncreased(uint _marketplaceId, address _provider, uint _liquidity, uint _amount0, uint _amount1)
• ProviderUnregistered(uint _marketplaceId, address _provider)
• OfferCreated(uint _marketplaceId, uint _offerId)
• OfferUpdated(uint _marketplaceId, uint _offerId)
• OfferDeleted(uint _marketplaceId, uint _offerId)
• ClientUpdated(uint _marketplaceId, address _client)
• DealCreated(uint _marketplaceId, uint _dealId, uint _amount, bool _autoAccept)
• DealAccepted(uint _marketplaceId, uint _dealId, uint _amount)
• DealRejected(uint _marketplaceId, uint _dealId, uint _clientRefund)
• DealCancelled(uint _marketplaceId, uint _dealId, uint _paymentToProvider, uint _totalPayment, uint _clientRefund)
• DealCollected(uint _marketplaceId, uint _dealId, uint _paymentToProvider, uint _totalPayment)
• AddedBalance(uint _marketplaceId, uint _blockedBalance, uint _dealId)
• BillingStartExtended(uint marketplaceId, uint dealId, uint _extension)

---

Modifiers

Modifiers are used to conditionally change the behavior of functions. For instance, certain functions can only be executed by the contract owner or by authorized proxies.

onlyAuthorized

The onlyAuthorized modifier ensures that tx.origin is the same as msg.sender or that msg.sender is an authorized proxy. This is implemented to ensure that only the actual providers, clients, or authorized proxies such as the Marketplace Helper can execute specific functions.

onlyRole(DEFAULT_ADMIN_ROLE)

The onlyRole(DEFAULT_ADMIN_ROLE) modifier ensures that msg.sender is an admin.

nonReentrant

This modifier makes sure that the function can't be executed again until the previous execution has finished.