crossbar.edge.worker.xbr._marketmaker¶

Classes¶

MarketMaker

XBR Market Maker. This is the off-chain delegate software component running for the market operator.

Module Contents¶

class MarketMaker(controller, maker_id, config, xbrmm_db, ipfs_files_dir)[source]¶

Bases: object

XBR Market Maker. This is the off-chain delegate software component running for the market operator. A market maker is always started for a specific XBR data market identified by the market ID (a 16 bytes UUID) which is stored on-chain (inside the XBRNetwork contract). There can be at most one market maker running for a given XBR data market.

The following WAMP events are published by the market maker:

xbr.marketmaker.on_status
xbr.marketmaker.delegate.<seller-delegate-adr>.on_offer_placed
xbr.marketmaker.delegate.<seller-delegate-adr>.on_offer_revoked
xbr.marketmaker.delegate.<buyer-delegate-adr>.on_payment_channel_open
xbr.marketmaker.delegate.<buyer-delegate-adr>.*
xbr.marketmaker.delegate.<seller-delegate-adr>.on_paying_channel_open
xbr.marketmaker.delegate.<seller-delegate-adr>.*

Note

The market ID is not part of the URIs above since each XBR data market is run on its own dedicated realm, so there is no need to duplicate that information in the URI.

STATUS_NONE = 0[source]¶

STATUS_RUNNING = 1[source]¶

STATUS_SHUTDOWN_IN_PROGRESS = 2[source]¶

STATUS_STOPPED = 3[source]¶

_chain_id[source]¶

_coin = None[source]¶

_config[source]¶

_controller_session[source]¶

_db[source]¶

_eth_acct[source]¶

_eth_adr[source]¶

_eth_adr_raw[source]¶

_eth_privkey[source]¶

_get_active_channel_and_balance(delegate_adr, channel_type)[source]¶

Queries the database index tables

idx_payment_channel_by_delegate
idx_paying_channel_by_recipient

which contain the currently active payment/paying channel per buyer/seller delegate address.

_id[source]¶

_inventory[source]¶

_ipfs_files_dir[source]¶

_market[source]¶

_market_id = None[source]¶

_market_oid = None[source]¶

_market_session = None[source]¶

_owner = None[source]¶

_reactor[source]¶

_schema[source]¶

_send_closeChannel(channelId: bytes, closeAt: int, channelSeq: int, balance: int, isFinal: bool, delegateSignature: bytes, marketmakerSignature: bytes)[source]¶

_send_openChannel(ctype: int, openedAt: int, marketId: bytes, channelId: bytes, actor: bytes, delegate: bytes, marketmaker: bytes, recipient: bytes, amount: int, signature: bytes)[source]¶

_send_setConsent(marketId: bytes, delegate: bytes, delegateType: int, apiCatalog: bytes, consent: bool, servicePrefix: str)[source]¶

_status = 0[source]¶

_transfer_tokens(sender, recipient, amount)[source]¶

Parameters:

sender (bytes)
recipient (bytes)
amount (int) – XBR tokens to transfer

Returns:

_uri_prefix = 'xbr.marketmaker.'[source]¶

_verifying_chain_id = None[source]¶

_verifying_contract = None[source]¶

_verifying_contract_adr = None[source]¶

_w3[source]¶

_xbr[source]¶

_xbrmm_db[source]¶

property address[source]¶

Market maker address.

Returns:: Checksum address of market maker.
Return type:: str

async buy_key(delegate_adr, buyer_pubkey, key_id, channel_oid, channel_seq, amount, balance, signature, details: autobahn.wamp.types.CallDetails | None = None)[source]¶

Called by a XBR Consumer to buy a key. The market maker will (given sufficient balance) forward the purchase request and call into the XBR Provider selling the key.

Parameters:

delegate_adr (bytes of length 20) – The buyer delegate Ethereum address. The technical buyer is usually the XBR delegate of the XBR consumer/buyer of the data being bought.
buyer_pubkey (bytes of length 32) – The buyer delegate Ed25519 public key.
key_id (bytes of length 16) – The UUID of the data encryption key to buy.
channel_oid (bytes of length 20) – The on-chain channel contract address.
channel_seq (int) – Payment channel off-chain transaction sequence number.
amount (bytes) – Amount signed off to pay. The actual amount paid is always less than or equal to this, but the amount must be greater than or equal to the price in the offer for selling the data encryption key being bought.
balance (bytes) – Balance remaining in the payment channel (from the buyer delegate to the market maker) after successfully buying the key.
signature (bytes) – Signature over the supplied buying information, using the Ethereum private key of the buyer delegate.
details (autobahn.wamp.types.CallDetails) – Caller details. The call will come from the XBR buyer delegate.

Returns:

Buying receipt, including the actual data encryption key that was bought. The data encryption key is itself encrypted (sealed) to the buyer_pubkey.

Return type:

dict

async close_channel(channel_oid: bytes, verifying_chain_id: int, current_block_number: int, verifying_contract_adr: bytes, closing_balance: bytes, closing_seq: int, closing_is_final: bool, delegate_signature: bytes, details: autobahn.wamp.types.CallDetails | None = None) → dict[source]¶

Trigger closing this channel.

When the first participant has triggered closing the channel, submitting its latest transaction/state, a timeout period begins during which the other participant in this channel can 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.

Parameters:

channel_oid – OID of the channel to close.
verifying_chain_id – Blockchain ID.
current_block_number – Blockchain current block number.
verifying_contract_adr – Address of XBRNetwork smart contract.
closing_balance – Close this channel at this remaining channel off-chain balance.
closing_seq – Close this channel at this last transaction sequence number for the channel.
closing_is_final – Flag indicating a promise by the signing participant (either delegate or market maker) that this is the latest transaction it will ever submit, regardless of any non-expired channel timeout. When both participants close a channel co-operatively, and both have submitted a last transaction with this flag set, the channel contract can close the channel without timeout (“instant cooperative channel close”).
delegate_signature – EIP712 delegate signature for closing the channel with the supplied data.
details (autobahn.wamp.types.CallDetails) – Caller details.

Returns:

XBR channel information.

property coin[source]¶

Market coin address.

Returns:: Checksum address of market coin (an ERC20 token).
Return type:: str

property db[source]¶

Market maker database.

Returns:: Handle to the embedded zLMDB database.
Return type:: object

abstractmethod find_consents(created_from: int | None = None, limit: int | None = None, include_owners: List[bytes] | None = None, include_delegates: List[bytes] | None = None, include_markets: List[bytes] | None = None, include_apis: List[bytes] | None = None, include_titles: List[str] | None = None, include_descriptions: List[str] | None = None, include_tags: List[str] | None = None, details: autobahn.wamp.types.CallDetails | None = None) → List[bytes][source]¶

Async:

Search for XBR Consents by

owning member (the member that gave consent)
descriptive title, description and tags
delegates the consents were given to

as well as specify range and limit of the searched blockchain blocks and returned catalogs.

See also

Unit test fixme.py

Note

When a specific filter is not provided, the filter remains un-applied and respective consents are not filtered in the results. Specifically, when called without any arguments, this procedure will return all existing consents. The pagination via created_from and limit still applies.

Parameters:

created_from – Only return consents created within blocks not earlier than this block number.
limit – Only return consents from this many blocks beginning with block created_from. So limit is in number of blocks and must be a positive integer when provided.

To search for consents, the following filters can be used:

Parameters:

include_owners – If provided, only return consents owned by any of the owners specified.
include_delegates – If provided, only return consents for any of the delegates specified.
include_markets – If provided, only return consents in any of the markets specified.
include_apis – If provided, only return consents for any of the APIs specified.
include_titles – If provided, only return consents with a title that contains any of the specified titles.
include_descriptions – If provided, only return consents with a description that contains any of the specified descriptions.
include_tags – If provided, only return consents with a tag that contains any of the specified tags.

FOR INTERNAL USE

Parameters:: details (autobahn.wamp.types.CallDetails) – DO NOT USE. Caller details internally provided by the router and cannot be used as an application level parameter.
Returns:: List of OIDs of consents matching the search criteria.

get_active_paying_channel(delegate_adr, details: autobahn.wamp.types.CallDetails | None = None)[source]¶

Returns the currently active paying channel for a seller delegate.

Parameters:

delegate_adr (bytes) – XBR seller delegate address.
details (autobahn.wamp.types.CallDetails) – Call details.

Returns:

Paying channel and balance details: (channel, balance).

Return type:

tuple

get_active_payment_channel(delegate_adr, details: autobahn.wamp.types.CallDetails | None = None)[source]¶

Returns the currently active payment channel and balance for a buyer delegate.

Parameters:

delegate_adr (bytes) – XBR buyer delegate address.
details (autobahn.wamp.types.CallDetails) – Call details.

Returns:

Payment channel and balance details: (channel, balance).

Return type:

tuple

async get_catalogs_by_owner(owner_adr: bytes, details: autobahn.wamp.types.CallDetails | None = None)[source]¶

Parameters:: owner_adr – Wallet address of the owner of the catalogs

FOR INTERNAL USE

Parameters:: details (autobahn.wamp.types.CallDetails) – DO NOT USE. Caller details internally provided by the router and cannot be used as an application level parameter.
Returns:: List of OIDs of catalogs matching the search criteria.

get_channels_by_actor(member_adr, channel_type, filter_open=True, details: autobahn.wamp.types.CallDetails | None = None)[source]¶

get_channels_by_delegate(delegate_adr: bytes, channel_type: int, filter_open: bool | None = True, details: autobahn.wamp.types.CallDetails | None = None)[source]¶

async get_config(include_eula_text: bool = False, details: autobahn.wamp.types.CallDetails | None = None) → dict[source]¶

get_consent(market_oid: bytes, member: bytes, delegate: bytes, delegate_type: int, catalog_oid: bytes, include_attributes: bool = False, details: autobahn.wamp.types.CallDetails | None = None) → dict[source]¶

async get_gas_price(details: autobahn.wamp.types.CallDetails | None = None) → bytes[source]¶

get_offer(offer_id, details: autobahn.wamp.types.CallDetails | None = None)[source]¶

Get detail information on a data encryption key offer previously placed by a XBR seller (delegate).

Parameters:: details (autobahn.wamp.types.CallDetails) – Caller details.
Returns:: Detail information about the offer requested.
Return type:: dict

get_paying_channel(channel_oid, details: autobahn.wamp.types.CallDetails | None = None)[source]¶

Returns the (off-chain) paying channel given by the (on-chain) paying channel contract address.

Parameters:

channel_oid (bytes) – Paying channel contract address.
details (autobahn.wamp.types.CallDetails) – Call details.

Returns:

Paying channel information.

Return type:

dict

get_paying_channel_balance(channel_oid, details: autobahn.wamp.types.CallDetails | None = None)[source]¶

Returns the (off-chain, real-time) paying channel balance given by the (on-chain) payment channel contract address.

Parameters:

channel_oid (bytes) – Paying channel contract address.
details (autobahn.wamp.types.CallDetails) – Call details.

Returns:

Paying channel balance information.

Return type:

dict

get_payment_channel(channel_oid, details: autobahn.wamp.types.CallDetails | None = None)[source]¶

Returns the (off-chain) payment channel given by the (on-chain) payment channel contract address.

Parameters:

channel_oid (bytes) – Payment channel contract address.
details (autobahn.wamp.types.CallDetails) – Call details.

Returns:

Payment channel information.

Return type:

dict

get_payment_channel_balance(channel_oid, details: autobahn.wamp.types.CallDetails | None = None)[source]¶

Returns the (off-chain, real-time) payment channel balance given by the (on-chain) payment channel contract address.

Parameters:

channel_oid (bytes) – Payment channel contract address.
details (autobahn.wamp.types.CallDetails) – Call details.

Returns:

Payment channel balance information.

Return type:

dict

get_quote(key_id, details: autobahn.wamp.types.CallDetails | None = None)[source]¶

Called by a XBR Consumer to get a price quote for a key. The market maker will forward the call to the XBR Provider selling the key if the price is dynamic. When the price is static, the XBR Market Maker will cache the price and return the cached value subsequently.

Parameters:

key_id (bytes) – UUID of the data encryption key to quote the price for.
details (autobahn.wamp.types.CallDetails) – Caller details. In this case XBR data consumer (XBR buyer delegates)

Returns:

The price quotation.

Return type:

dict

async get_status(details: autobahn.wamp.types.CallDetails | None = None) → dict[source]¶

async get_transaction_receipt(transaction: bytes, details: autobahn.wamp.types.CallDetails | None = None) → dict[source]¶

log[source]¶

property market[source]¶

Market ID.

Returns:: UUID of market.
Return type:: uuid.UUID

async open_channel(member_adr: bytes, market_oid: bytes, channel_oid: bytes, verifying_chain_id: int, current_block_number: int, verifying_contract_adr: bytes, channel_type: int, delegate: bytes, marketmaker: bytes, recipient: bytes, amount: bytes, signature: bytes, attributes: dict | None = None, details: autobahn.wamp.types.CallDetails | None = None) → dict[source]¶

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

Parameters:

member_oid – OID of the member that sets the XBR consent status.
market_oid – OID of the market (the member must be actor in) in which the member set the consent status.
channel_oid – New channel OID.
verifying_chain_id – Blockchain ID.
current_block_number – Blockchain current block number.
verifying_contract_adr – Address of XBRNetwork smart contract.
channel_type – Channel type: payment or paying 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).
recipient – The address of the beneficiary for any channel payout when the channel is closed.
amount – The amount initially transfered to and held in the channel until closed.
signature – EIP712 signature for opening the channel.
attributes – Object standard attributes like title, description and tags.
details (autobahn.wamp.types.CallDetails) – Caller details.

Returns:

XBR channel information.

property owner[source]¶

Market owner address.

Returns:: Checksum address of market owner.
Return type:: str

async place_offer(key_id, api_id, uri, valid_from, delegate_adr, delegate_signature, privkey=None, price=None, categories=None, expires=None, copies=None, provider_id=None, details: autobahn.wamp.types.CallDetails | None = None)[source]¶

Called by a XBR Provider (XBR Seller delegate) to offer a data encryption key for sale. A key is offered as applying to a specific API, and the key price, and the URI under which the data is provided must be specified.

The offer can either use uniform pricing or dynamic pricing. With uniform pricing, a price must be specified. The price can be zero or more XBR tokens. With dynamic pricing (price==None), the market maker will call into the XBR seller delegate whenever quoted by a buyer, or to get a binding quotes requested by the market maker itself so ensure sufficicient balance before executing a key buying transaction for a buyer.

Optionally, a seller (delegate) may specify app or user defined categories under which the key is to be offered. The category or categories allow buyers to filter offers for keys for data they might be interested in.

Further, optionally a seller can specify a key expiration date as well as a maximum number of copies a key is to be sold.

Parameters:

key_id (bytes) – UUID of the data encryption key offered.
api_id (bytes) – UUID of the API the encrypted data (this key is for) is provided under.
uri (str) – URI (prefix) under which the data encrypted with the key offered is provided under.
valid_from (int) – Timestamp from which the offer is valid.
delegate_adr (bytes) – Seller delegate address.
delegate_signature (bytes) – Seller delegate signature.
privkey (bytes) – Optional actual data encryption private key sold. This is when the market maker is trusted with the actual selling (eg to save on the otherwise resulting calls into the seller delegate). When no private key is submitted with the offer, the market maker will call into the seller delegate during key buying transactions.
price (bytes) – Price of data encryption key in XBR tokens.
categories (dict) – Optional user defined categories the specific data that is provided falls under.
expires (int) – Optional data at which this offer expires (epoc time in ns).
copies (int) – Optional maximum number of times this data encryption key is to be sold or 0 for unlimited.
details (autobahn.wamp.types.CallDetails) – Caller details. In this case XBR data providers (XBR seller delegates)

Returns:

Offer placement information, including offer ID assigned.

Return type:

dict

query_offers(api_id, from_ts, until_ts=None, uri=None, categories=None, seller_id=None, limit=None, details: autobahn.wamp.types.CallDetails | None = None)[source]¶

Return data encryption key offers for the given API and timerange, optionally filtered by one or more categories.

Note

Only offers that have not expired and that still have copies remaining to be sold are returned, if the original key offer did have an expiration date and/or maximum copies specified.

Here is an example that retrieves all key offers in Python for some API within the last hour:

last_hour = time_ns() - 60 * 60 * 10**9

offers = await session.call('xbr.marketmaker.query_offers', api_id, last_hour)

To filter for categories, here is how to retrieve all key offers that match a specific category:

categories = {'vehicle_id': '92123a39-6422-4892-adf0-932892dc0c17}

offers = await session.call('xbr.marketmaker.query_offers', api_id, last_hour, categories=categories)

Filters can be given for more than one category, and combined with time filtering:

from_ts = int(datetime(2019, 2, 10).timestamp() * 10**9)
until_ts = int(datetime(2019, 2, 11).timestamp() * 10**9)
categories = {'xtile': 132115, 'ytile': 95682, 'zoom': 18})

offers = await session.call('xbr.marketmaker.query_offers', api_id, from_ts, until_ts=until_ts,
                            categories=categories)

Parameters:

api_id (bytes) – UUID of the API the offers are for.
from_ts (int) – Return offers since this date (Unix epoch time in ns).
until_ts (int) – If given, only return offers up to this date (Unix epoch time in ns), otherwise return all order up till now.
uri (str) – Optional URI prefix to filter offers for.
categories (dict) – Optional user defined categories to filter offers for.
seller_id (bytes) – Optional UUID of a specific seller to filter offers for.
limit (int) – If given, return at most this many offers. Default: 10. The maximum value for limit that can be specified is 1000.
details (autobahn.wamp.types.CallDetails) – Caller details. In this case XBR data consumer (XBR buyer delegates)

Returns:

Returns a list of data encryption key offers.

Return type:

list

revoke_offer(key_id, details: autobahn.wamp.types.CallDetails | None = None)[source]¶

Called by XBR Provider to revoke (on-going) sale of a key. The market maker will stop accepting purchase requests for the given key and buyers attempting to buy the key will get a key expiration error.

Note

Only the original seller (delegate) that offered the key may revoke a key offering.

Parameters:

key_id (bytes) – UUID of the data encryption key to revoke.
details (autobahn.wamp.types.CallDetails) – Caller details. In this case XBR data provider (XBR seller delegates)

Returns:

Offer revocation information.

Return type:

dict

property schema[source]¶

Market maker database schema.

Returns:: Schema of the embedded zLMDB database.
Return type:: object

async set_consent(member_adr: bytes, market_oid: bytes, verifying_chain_id: int, current_block_number: int, verifying_contract_adr: bytes, delegate: bytes, delegate_type: int, catalog_oid: bytes, consent: bool, service_prefix: str, signature: bytes, attributes: dict | None = None, details: autobahn.wamp.types.CallDetails | None = None) → dict[source]¶

Set XBR data consent status.

The consent must be signed by the member, and the member must have joined the market (the member must be a provider or consumer actor in the market).

Consent is given by the member to the specified delegate within the specified market, to provide or consume data - depending on delegate_type - under any XBR data API published to the given XBR data catalog. The data is provided or consumed under the respective data market terms and data catalog terms.

Parameters:

member_adr – Wallet address of the member that sets the XBR consent status.
market_oid – OID of the market (the member must be actor in) in which the member set the consent status.
verifying_chain_id – Blockchain ID.
current_block_number – Blockchain current block number.
verifying_contract_adr – Address of XBRNetwork smart contract.
delegate – Address of delegate consent (status) applies to.
delegate_type – The delegate type (consumer or provider) this consent applies to. Note that consent can be given to a delegate (identified by its address) as both consumer and provider, and also for different API catalogs and markets.
catalog_oid – The OID of the XBR API catalog consent is given for. Depending on delegate_type, the delegate may then - depending on consent granted or forbidden (which is the default) - consume or provide data under an API from the catalog.
consent – Status flag indicating whether consent is granted or forbidden.
service_prefix – The WAMP URI prefix of the delegate under which it provides services implementing the APIs in the catalog. This URI must be globally unique for the delegate. Consumers of the service will access the delegate by using its service_prefix and under the respective API definition (eg what WAMP procedures and topics are provided by the service, and the types of application payloads used in procedures and topics.
signature – EIP712 signature for setting XBR consent (signed by member).
details (autobahn.wamp.types.CallDetails) – Caller details.

Returns:

XBR Consent setting information.

start()[source]¶

Returns:

async status(details: autobahn.wamp.types.CallDetails | None) → dict[source]¶

Get market maker status and blockchain synchronization information.

Parameters:: details – Caller details.
Returns:: Market maker status and blockchain synchronization information.

stop()[source]¶

Returns: