Contracts Reference¶

This is the public API reference documentation for the XBR protocol smart contracts:

Note

The contracts are written in Solidity, and the documentation here is generated directly from the docstrings in the XBR contracts source code using Sphinx and Solidity domain for Sphinx.

XBRToken ¶

contract XBRToken is ERC20¶

The XBR Token is a ERC20 standard token defined by:

“XBR” as symbol
fixed total supply of 10**9 (“one billion”) XBR
18 decimals
address (mainnet): tbd

The XBR Token is using the (unmodified) OpenZeppelin reference implementation of the ERC20 token standard.

For API documentation, please see here.

uint256 private constant INITIAL_SUPPLY¶: The XBR Token has a fixed supply of 1 billion and uses 18 decimal digits.

mapping (bytes32 => uint256) private burnedSignatures¶: For pre-signed transactions (“approveFor”), track signatures already used.

constructor()¶ public ERC20("XBRToken", "XBR") ¶: Constructor that gives msg.sender all of existing tokens. The XBR Token uses the symbol “XBR” and 18 decimal digits.

approveFor ¶

function approveFor(address sender, address relayer, address spender, uint256 amount, uint256 expires, uint256 nonce, bytes memory signature)¶ public returns (bool) ¶

This method provides an extension to the standard ERC20 interface that allows to approve tokens to be spent by another party or contract, similar to the standard IERC20.approve method.

The difference is, that by using this method, the sender can pre-sign the approval off-chain, and then let another party (the relayer) submit the transaction to the blockchain. Only the relayer needs to have ETH to pay for gas, the off-chain sender does _not_ need any ETH.

Parameters:

sender – The (off-chain) sender of tokens.
relayer – If given, the metatransaction can only be relayed from this address.
spender – The spender that will spend the tokens approved.
amount – Token amount to approve for the spender to spend.
expires – If given, the signature will expire at this block number.
nonce – Random nonce for metatransaction.
signature – Signature over EIP712 data, signed by sender.

burnSignature ¶

function burnSignature(address sender, address relayer, address spender, uint256 amount, uint256 expires, uint256 nonce, bytes memory signature)¶ public returns (bool success) ¶: This method allows a sender that approved tokens via approveFor to burn the metatransaction that was sent to the relayer - but only if the transaction has not yet been submitted by the relay.

XBRNetwork ¶

contract XBRNetwork is XBRMaintained¶

The XBR Network contract is the on-chain anchor of and the entry point to the XBR protocol.

event MemberRegistered(address indexed member, uint registered, string eula, string profile, XBRTypes.MemberLevel level)¶ ¶: Event emitted when a new member registered in the XBR Network.

event MemberChanged(address indexed member, uint changed, string eula, string profile, XBRTypes.MemberLevel level)¶ ¶: Event emitted when an existing member is changed (without leaving the XBR Network).

event MemberRetired(address member, uint retired)¶ ¶: Event emitted when a member leaves the XBR Network.

event CoinChanged(address indexed coin, address operator, bool isPayable)¶ ¶: Event emitted when the payable status of a coin is changed.

address public constant ANYADR¶: Special addresses used as “any address” marker in mappings (eg coins).

uint256 public verifyingChain¶: Chain ID of the blockchain this contract is running on, used in EIP712 typed data signature verification.

address public verifyingContract¶: Verifying contract address, used in EIP712 typed data signature verification.

string public eula¶: IPFS multihash of the XBR Network EULA.

uint256 public contribution¶: XBR network contributions from markets for the XBR project, expressed as a fraction of the total amount of XBR tokens.

XBRToken public token¶: Address of the XBR Networks’ own ERC20 token for network-wide purposes.

address public organization¶: Address of the XBR Network Organization.

mapping (address => XBRTypes.Member) public members¶: Current XBR Network members (“member directory”).

mapping (address => mapping (address => bool)) public coins¶: ERC20 coins which can specified as a means of payment when creating a new data market.

constructor(address networkToken, address networkOrganization)¶ public ¶

Create the XBR network.

Parameters:

networkToken – The token to run this network itself on. Note that XBR data markets can use any ERC20 token (enabled in the coins mapping of this contract) as a means of payment in the respective market.
networkOrganization – The XBR network organization address.

function setNetworkToken(address networkToken)¶ public onlyMaintainer returns (bool) ¶

Set the XBR network organization address.

Parameters:

networkToken – The token to run this network itself on. Note that XBR data markets can use any ERC20 token (enabled in the coins mapping of this contract) as a means of payment in the respective market.

function setNetworkOrganization(address networkOrganization)¶ public onlyMaintainer returns (bool) ¶

Set the XBR network organization address.

Parameters:

networkOrganization – The XBR network organization address.

function setMemberLevel(address member, XBRTypes.MemberLevel level)¶ public onlyMaintainer returns (bool) ¶

Set (override manually) the member level of a XBR Network member. Being able to do so currently serves two purposes:

having a last resort to handle situation where members violated the EULA
being able to manually patch things in error/bug cases

Parameters:

member – The address of the XBR network member to override member level.
level – The member level to set the member to.

function setCoinPayable(address coin, address operator, bool isPayable)¶ public onlyMaintainer returns (bool) ¶

Set ERC20 coins as usable as a means of payment when opening data markets.

Parameters:

coin – The address of the ERC20 coin to change.
isPayable – When true, the coin can be specified when opening a new data market.

function setContribution(uint256 networkContribution)¶ public onlyMaintainer returns (bool) ¶

Set the network contribution which is deducted from the market fees defined by a market operator.

Parameters:

networkContribution – Network contribution, defined as the ratio of given number of tokens and the total token supply.

Return:

Flag indicating whether the contribution value was actually changed.

registerMember ¶

function registerMember(string memory networkEula, string memory memberProfile)¶ public ¶

Register the sender of this transaction in the XBR network. All XBR stakeholders, namely data providers (“sellers”), data consumers (“buyers”) and data market operators, must be registered in the XBR network.

Parameters:

networkEula – Multihash of the XBR EULA being agreed to and stored as one ZIP file archive on IPFS.
memberProfile – Optional public member profile: the IPFS Multihash of the member profile stored in IPFS.

registerMemberFor ¶

function registerMemberFor(address member, uint256 registered, string memory networkEula, string memory memberProfile, bytes memory signature)¶ public ¶

Register the specified new member in the XBR Network. All XBR stakeholders, namely data providers (“sellers”), data consumers (“buyers”) and data market operators, must be registered in the XBR network.

Note: This version uses pre-signed data where the actual blockchain transaction is submitted by a gateway paying the respective gas (in ETH) for the blockchain transaction.

Parameters:

member – Address of the registering (new) member.
registered – Block number at which the registering member has created the signature.
networkEula – Multihash of the XBR EULA being agreed to and stored as one ZIP file archive on IPFS.
memberProfile – Optional public member profile: the IPFS Multihash of the member profile stored in IPFS.
signature – EIP712 signature, signed by the registering member.

XBRCatalog ¶

contract XBRCatalog is XBRMaintained¶

XBR API catalogs contract.

event CatalogCreated(bytes16 indexed catalogId, uint256 created, uint32 catalogSeq, address owner, string terms, string meta)¶ ¶: Event emitted when a new catalog was created.

event ApiPublished(bytes16 indexed catalogId, bytes16 apiId, uint256 published, string schema, string meta)¶ ¶: Event emitted when an API has been published to a catalog.

XBRNetwork public network¶: Instance of XBRNetwork contract this contract is linked to.

uint32 private catalogSeq¶: Created catalogs are sequence numbered using this counter (to allow deterministic collision-free IDs for markets)

mapping (bytes16 => XBRTypes.Catalog) public catalogs¶: Current XBR Catalogs (“catalog directory”)

bytes16[] public catalogIds¶: List of IDs of current XBR Catalogs.

constructor(address networkAdr)¶ public ¶

function createCatalog(bytes16 catalogId, string memory terms, string memory meta)¶ public ¶

Create a new XBR catalog. The sender of the transaction must be XBR network member and automatically becomes owner of the new catalog.

Parameters:

catalogId – The ID of the new catalog.
terms – Multihash for terms that apply to the catalog and to all APIs as published to this catalog.
meta – Multihash for optional catalog meta-data.

function createCatalogFor(address member, uint256 created, bytes16 catalogId, string memory terms, string memory meta, bytes memory signature)¶ public ¶

Create a new XBR catalog for a member. The member must be XBR network member, must have signed the transaction data, and will become owner of the new catalog.

Note: This version uses pre-signed data where the actual blockchain transaction is submitted by a gateway paying the respective gas (in ETH) for the blockchain transaction.

Parameters:

member – Member that creates the catalog and will become owner.
created – Block number when the catalog was created.
catalogId – The ID of the new catalog.
terms – Multihash for terms that apply to the catalog and to all APIs as published to this catalog.
meta – Multihash for optional catalog meta-data.
signature – Signature created by the member.

function _createCatalog(address member, uint256 created, bytes16 catalogId, string memory terms, string memory meta, bytes memory signature)¶ private ¶

function publishApi(bytes16 catalogId, bytes16 apiId, string memory schema, string memory meta)¶ public ¶

Publish the given API to the specified catalog.

Parameters:

catalogId – The ID of the XBR API catalog to publish the API to.
apiId – The ID of the new API (must be unique).
schema – Multihash of API Flatbuffers schema (required).
meta – Multihash for optional meta-data.

function publishApiFor(address member, uint256 published, bytes16 catalogId, bytes16 apiId, string memory schema, string memory meta, bytes memory signature)¶ public ¶

Publish the given API to the specified catalog.

Note: This version uses pre-signed data where the actual blockchain transaction is submitted by a gateway paying the respective gas (in ETH) for the blockchain transaction.

Parameters:

member – Member that is publishing the API.
published – Block number when the API was published.
catalogId – The ID of the XBR API catalog to publish the API to.
apiId – The ID of the new API (must be unique).
schema – Multihash of API Flatbuffers schema (required).
meta – Multihash for optional meta-data.
signature – Signature created by the member.

function _publishApi(address member, uint256 published, bytes16 catalogId, bytes16 apiId, string memory schema, string memory meta, bytes memory signature)¶ private ¶

createCatalog ¶

function createCatalog(bytes16 catalogId, string memory terms, string memory meta)¶ public ¶

Create a new XBR catalog. The sender of the transaction must be XBR network member and automatically becomes owner of the new catalog.

Parameters:

catalogId – The ID of the new catalog.
terms – Multihash for terms that apply to the catalog and to all APIs as published to this catalog.
meta – Multihash for optional catalog meta-data.

createCatalogFor ¶

function createCatalogFor(address member, uint256 created, bytes16 catalogId, string memory terms, string memory meta, bytes memory signature)¶ public ¶

Create a new XBR catalog for a member. The member must be XBR network member, must have signed the transaction data, and will become owner of the new catalog.

Note: This version uses pre-signed data where the actual blockchain transaction is submitted by a gateway paying the respective gas (in ETH) for the blockchain transaction.

Parameters:

member – Member that creates the catalog and will become owner.
created – Block number when the catalog was created.
catalogId – The ID of the new catalog.
terms – Multihash for terms that apply to the catalog and to all APIs as published to this catalog.
meta – Multihash for optional catalog meta-data.
signature – Signature created by the member.

publishApi ¶

function publishApi(bytes16 catalogId, bytes16 apiId, string memory schema, string memory meta)¶ public ¶

Publish the given API to the specified catalog.

Parameters:

catalogId – The ID of the XBR API catalog to publish the API to.
apiId – The ID of the new API (must be unique).
schema – Multihash of API Flatbuffers schema (required).
meta – Multihash for optional meta-data.

publishApiFor ¶

function publishApiFor(address member, uint256 published, bytes16 catalogId, bytes16 apiId, string memory schema, string memory meta, bytes memory signature)¶ public ¶

Publish the given API to the specified catalog.

Note: This version uses pre-signed data where the actual blockchain transaction is submitted by a gateway paying the respective gas (in ETH) for the blockchain transaction.

Parameters:

member – Member that is publishing the API.
published – Block number when the API was published.
catalogId – The ID of the XBR API catalog to publish the API to.
apiId – The ID of the new API (must be unique).
schema – Multihash of API Flatbuffers schema (required).
meta – Multihash for optional meta-data.
signature – Signature created by the member.

XBRMarket ¶

contract XBRMarket is XBRMaintained¶

The XBR Market contract manages XBR data markets and serves as an anchor for all payment and paying channels for each respective market.

event MarketCreated(bytes16 indexed marketId, uint created, uint32 marketSeq, address owner, address coin, string terms, string meta, address maker, uint256 providerSecurity, uint256 consumerSecurity, uint256 marketFee)¶ ¶: Event emitted when a new market was created.

event MarketClosed(bytes16 indexed marketId)¶ ¶: Event emitted when a market was closed.

event ActorJoined(bytes16 indexed marketId, address actor, uint8 actorType, uint256 joined, uint256 security, string meta)¶ ¶: Event emitted when a new actor joined a market.

event ActorLeft(bytes16 indexed marketId, address actor, uint8 actorType, uint256 left, uint256 securitiesToBeRefunded)¶ ¶: Event emitted when an actor has left a market.

event ConsentSet(address member, uint256 updated, bytes16 marketId, address delegate, uint8 delegateType, bytes16 apiCatalog, bool consent, string servicePrefix)¶ ¶: Event emitted when an actor has set consent on a (market, delegate, api) triple.

XBRNetwork public network¶: Instance of XBRNetwork contract this contract is linked to.

mapping (bytes16 => XBRTypes.Market) public markets¶: Current XBR Markets (“market directory”)

bytes16[] public marketIds¶: List of IDs of current XBR Markets.

createMarket ¶

function createMarket(bytes16 marketId, address coin, string memory terms, string memory meta, address maker, uint256 providerSecurity, uint256 consumerSecurity, uint256 marketFee)¶ public ¶

Create a new XBR market. The sender of the transaction must be XBR network member and automatically becomes owner of the new market.

Parameters:

marketId – The ID of the market to create. Must be unique (not yet existing).
coin – The ERC20 coin to be used as the means of payment in the market.
terms – Multihash for market terms set by the market owner.
meta – Multihash for optional market metadata.
maker – The address of the XBR market maker that will run this market. The delegate of the market owner.
providerSecurity – The amount of coins a XBR provider joining the market must deposit.
consumerSecurity – The amount of coins a XBR consumer joining the market must deposit.
marketFee – The fee taken by the market (beneficiary is the market owner). The fee is a percentage of the revenue of the XBR Provider that receives coins paid for transactions. The fee must be between 0% (inclusive) and 100% (inclusive), and is expressed as a fraction of the total supply of coins in the ERC20 token specified for the market.

createMarketFor ¶

function createMarketFor(address member, uint256 created, bytes16 marketId, address coin, string memory terms, string memory meta, address maker, uint256 providerSecurity, uint256 consumerSecurity, uint256 marketFee, bytes memory signature)¶ public ¶

Create a new XBR market for a member. The member must be XBR network member, must have signed the transaction data, and will become owner of the new market.

Note: This version uses pre-signed data where the actual blockchain transaction is submitted by a gateway paying the respective gas (in ETH) for the blockchain transaction.

Parameters:

member – The member that creates the market (will become market owner).
created – Block number when the market was created.
marketId – The ID of the market to create. Must be unique (not yet existing).
coin – The ERC20 coin to be used as the means of payment in the market.
terms – Multihash for market terms set by the market owner.
meta – Multihash for optional market metadata.
maker – The address of the XBR market maker that will run this market. The delegate of the market owner.
providerSecurity – The amount of coins a XBR provider joining the market must deposit.
consumerSecurity – The amount of coins a XBR consumer joining the market must deposit.
marketFee – The fee taken by the market (beneficiary is the market owner). The fee is a percentage of the revenue of the XBR Provider that receives coins paid for transactions. The fee must be between 0% (inclusive) and 100% (inclusive), and is expressed as a fraction of the total supply of coins in the ERC20 token specified for the market.
signature – EIP712 signature created by the member.

joinMarket ¶

function joinMarket(bytes16 marketId, uint8 actorType, string memory meta)¶ public returns (uint256) ¶

Join the given XBR market as the specified type of actor, which must be PROVIDER or CONSUMER.

Parameters:

marketId – The ID of the XBR data market to join.
actorType – The type of actor under which to join: PROVIDER or CONSUMER.
meta – The XBR market provider/consumer metadata. IPFS Multihash pointing to a JSON file with metadata.

joinMarketFor ¶

function joinMarketFor(address member, uint256 joined, bytes16 marketId, uint8 actorType, string memory meta, bytes memory signature)¶ public returns (uint256) ¶

Join the specified member to the given XBR market as the specified type of actor, which must be PROVIDER or CONSUMER.

Note: This version uses pre-signed data where the actual blockchain transaction is submitted by a gateway paying the respective gas (in ETH) for the blockchain transaction.

Parameters:

member – The member that creates the market (will become market owner).
joined – Block number when the member joined the market.
marketId – The ID of the XBR data market to join.
actorType – The type of actor under which to join: PROVIDER or CONSUMER.
meta – The XBR market provider/consumer metadata. IPFS Multihash pointing to a JSON file with metadata.
signature – EIP712 signature created by the member.

setConsent ¶

function setConsent(bytes16 marketId, address delegate, uint8 delegateType, bytes16 apiCatalog, bool consent, string memory servicePrefix)¶ public ¶

Track consent of an actor in a market to allow the specified seller or buyer delegate to provide or consume data under the respective API catalog in the given market.

Parameters:

marketId – The ID of the XBR data market in which to provide or consume data. Any terms attached to the market or the API apply.
delegate – The address of the off-chain provider or consumer delegate, which is a piece of software acting on behalf and under consent of the actor in the market.
delegateType – The type of off-chain delegate, a data provider or data consumer.
apiCatalog – The ID of the API or API catalog to which the consent shall apply.
consent – Consent granted or revoked.
servicePrefix – The WAMP URI prefix to be used by the delegate in the data plane realm.

setConsentFor ¶

function setConsentFor(address member, uint256 updated, bytes16 marketId, address delegate, uint8 delegateType, bytes16 apiCatalog, bool consent, string memory servicePrefix, bytes memory signature)¶ public ¶

Track consent of an actor in a market to allow the specified seller or buyer delegate to provide or consume data under the respective API catalog in the given market.

IMPORTANT: This version uses pre-signed data where the actual blockchain transaction is submitted by a gateway paying the respective gas (in ETH) for the blockchain transaction.

Parameters:

member – Address of member (which must be actor in the market) that sets consent.
updated – Block number at which the consent setting member has created the signature.
marketId – The ID of the XBR data market in which to provide or consume data. Any terms attached to the market or the API apply.
delegate – The address of the off-chain provider or consumer delegate, which is a piece of software acting on behalf and under consent of the actor in the market.
delegateType – The type of off-chain delegate, a data provider or data consumer.
apiCatalog – The ID of the API or API catalog to which the consent shall apply.
consent – Consent granted or revoked.
servicePrefix – The WAMP URI prefix to be used by the delegate in the data plane realm.
signature – EIP712 signature, signed by the consent setting member.

XBRChannel ¶

contract XBRChannel is XBRMaintained¶

XBR Payment/Paying Channel between a XBR data consumer and the XBR market maker, or the XBR Market Maker and a XBR data provider.

event Opened(XBRTypes.ChannelType ctype, bytes16 indexed marketId, bytes16 indexed channelId, address actor, address delegate, address marketmaker, address recipient, uint256 amount, bytes signature)¶ ¶: Event emittedd when a new XBR data market has opened.

event Closing(XBRTypes.ChannelType ctype, bytes16 indexed marketId, bytes16 indexed channelId, uint256 payout, uint256 fee, uint256 refund, uint256 timeoutAt)¶ ¶: Event emitted when payment channel is closing (that is, one of the two state channel participants has called “close()”, initiating start of the channel timeout).

event Closed(XBRTypes.ChannelType ctype, bytes16 indexed marketId, bytes16 indexed channelId, uint256 payout, uint256 fee, uint256 refund, uint256 closedAt)¶ ¶: Event emitted when payment channel has finally closed, which happens after both state channel participants have called close(), agreeing on last state, or after the timeout at latest - in case the second participant doesn’t react within timeout)

XBRMarket public market¶: Instance of XBRMarket contract this contract is linked to.

mapping (bytes16 => XBRTypes.Channel) public channels¶: Table of all XBR Channels.

mapping (bytes16 => XBRTypes.ChannelClosingState) public channelClosingStates¶: Table of all XBR Channel closing states.

openChannel ¶

function openChannel(XBRTypes.ChannelType ctype, uint256 openedAt, bytes16 marketId, bytes16 channelId, address actor, address delegate, address marketmaker, address recipient, uint256 amount, bytes memory signature)¶ public ¶

Open a new XBR payment/paying channel for processing off-chain micro-transactions.

Parameters:

ctype – Channel type: payment or paying channel.
openedAt – Block number when the channel opening signature was created.
marketId – The ID of the XBR market this channel is associated with.
channelId – The ID of the new XBR channel (must be unique).
actor – The actor (buyer/seller in the market) that opened this channel.
delegate – The delegate (off-chain) allowed to spend/earn-on this channel (off-chain) in the name of the actor (buyer/seller in the market).
marketmaker – The off-chain market maker executing the channel.
recipient – The receiver (on-chain) of the channel payout.
amount – The amount initially transfered to and held in the channel until closed.
signature – EIP712 signature, signed by the member.

closeChannel ¶

function closeChannel(bytes16 channelId, uint256 closeAt, uint32 closingChannelSeq, uint256 balance, bool isFinal, bytes memory delegateSignature, bytes memory marketmakerSignature)¶ public ¶: Trigger closing this payment channel. When the first participant has called close() submitting its latest transaction/state, a timeout period begins during which the other party of the payment channel has to submit its latest transaction/state too. When both transaction have been submitted, and the submitted transactions/states agree, the channel immediately closes, and the consumed amount of token in the channel is transferred to the channel recipient, and the remaining amount of token is transferred back to the original sender.