RFC002: The Listings Service


Start Date	03/02/2025
Description	Define the APIs to handle the Listings service and accompanying integrations.
Authors	Pablo Andrés Dorado Suárez (hola@pablodorado.com)

Summary

This RFC defines the structure, behaviour and external integrations needed to support Listings, an abstraction to define and manage nonfungibles that represent goods and services, managed by merchants through the existing Payments system.

Motivation

Kreivo has been established as the DAO Hub: that is, the place where people can constitute DAOs, self-organise, and handle interactions across the entire network.

This scope, while a great prospect of what it can provide to the ecosystem, lacks fundamental tools when it comes to fostering meaningful commercial activity that incentivises these organisations to remain in Kreivo.

This document covers the necessary aspects to ensure these tools are available to DAOs in the form of merchant APIs that can be used through apps deployed by the organisations in the form of Smart Contracts, or by external systems through supporting SDKs (see RFC001).

Stakeholders

Communities at Kreivo.
Smart Contract builders.
Payments system users.

Explanation

Concepts

Listings: A Kreivo system that represents a catalog of merchandise that can be exchanged between commercial communities and customers.
Listing Item (or item): A non-fungible item that represents a class of a merchandisable item, which can be either a good, a service, or a recurring subscription.
Inventory: A set of items. Its organization is defined by the commerce which publishes the items.
Commercial community (commerce): An entity that publishes and exchanges listing items over the network, and uses the Payments system to support these exchanges.
Customer: An entity that interacts with the system by buying listing items.
Application: Any programmable mechanism (typically Smart Contracts) built by the commercial communities, that can interact with the Listings system, and other Kreivo systems (like Payments) through programmable interfaces (APIs).

Building blocks

Inventories

Commercial communities can create inventories. An inventory is identified by the ID of the commercial community, and an internally given ID defined by it when creating the inventory.

The internal ID (InventoryId) is an opaque field. This is, any structure that supports Encode and Decode can be encoded into a InventoryID field.

Items

An inventory contains items.

Each item contains the following basic information: an item ID (ItemId), a name, and a price (Price), the creator's identification (AccountId) and the owner's identification (AccountId).

The item price (ItemPrice) is a composite structure, comprised of the asset (AssetId) and an amount (Balance).

An item can be marked as "not for sale", meaning it's not necessary to include a price. Also, can be marked as "not for resale", disabling reselling it using this system (whether the item can be resold by external systems is outside the scope of this document).

The act of creating an item inside an inventory is called publishing an item.

Types of items

The system allows selling regular items, or subscriptions.

Subscriptions

A subscription is defined by appending information about the conditions of the subscription (subscription conditions): a price, and a renewal period (Moment). Also, a reference to the subscription terms and conditions might be included, but it's optional.

When a subscription is acquired by a customer, a new field (the subscription information) would appear on the item. This field includes the next renewal time, and the cost of the renewal.

The creator of the subscription can change the subscription conditions at any time. When this happens, an event MUST be emitted on the chain, to inform the affected subscriber.

A subscription can be cancelled by either the item's owner or creator. This clears the renewal task, and schedules a cancellation task that would remove the subscription information.

A subscription can be terminated by the creator of it, stating a reason of why the subscription was terminated. This triggers the removal of the subscription information from the item. This means the effects of the termination are immediate, allowing the commerce to cease the provided services bounded by the subscription promptly.

Termination Appeals

When terminated, the subscription information is stores, alongside the moment when it was terminated onto a separate structure that will live for up to a renewal period. The customer can use this information to submit an appeal, if appeals are available in the implementation.

The appeal process can be delegated onto an external Kreivo system. If resolved in favour of the customer, the result of the appeal is to re-enable the subscription information of the item, restoring the service, extend the renewal time between the moment it was terminated and when the appeal was resolved, and schedule a cancellation which can't be overriden by any party.

Linked items

TODO: Define what are linked items, the conditions behind them, and how they can be used to template or create composite items.

Payments

When creating a payment, a payment lock must be placed, disabling transferring, selling, changing the information fields, or destroying it.

If the customer is buying a regular item, a one-time payment will be created. Once settled, the item will be transferred from the current owner to the buyer.

If the customer is buying a subscription, a recurring payment will be created. Once settled, the subscription information will be included into the item, and the first renew task must be scheduled.

When the payment is settled or cancelled, the payment lock will be lifted.

Here is a proposal for the Drawbacks and Testing, Security, and Privacy sections based on your document:

Drawbacks

The Listings service requires extensive integration with the Payments system and additional governance for handling subscriptions and linked items. This complexity may increase development time and the likelihood of bugs.

Also, while Kreivo aims to provide a decentralized environment, relying on a specific implementation for payments and listings may create difficulties for external systems that want to interact with listings independently. We'll need to correctly define trait-based contract integrations between the systems.

Managing subscriptions and payment locks for high-volume transactions could introduce performance bottlenecks, particularly if subscription renewals are not efficiently handled in bulk operations. Also, we need to consider whether a recurring payment is cancelled, or the sub-payment cannot be executed, then what to do with the subscription? Suspend it (not considered yet)? Or terminate it?

Finally, if the appeal process for terminated subscriptions is not well-defined or efficiently managed, it could lead to abuse from either customers or merchants. Delays in appeal processing could also result in negative user experiences.

Testing, Security, and Privacy

Testing

Unit and Integration Testing:
- Ensure all traits are well-tested for expected behaviors, particularly item creation, transfer, and payment mechanisms.
- Subscription renewal logic should be stress-tested to validate correct timing and fee collection.
Edge Cases and Error Handling:
- Test how the system handles unexpected failures (e.g., expired payments, price updates in pending transactions).
- Verify correct behavior when a subscription is modified mid-term.
Cross-Module Testing:
- Ensure compatibility with Payments and other Kreivo services, particularly in cross-system interactions.

Security Considerations

Prevent Unauthorized Modifications:
- Only the item's owner or creator should be able to update item details.
- Subscription termination must enforce a transparent and verifiable process.
Protection Against Double-Spending and Fraud:
- Implement measures to ensure that an item cannot be transferred while locked in an incomplete transaction.
- Prevent misuse of appeals as a mechanism to extend service periods unfairly.

Privacy Considerations

Minimization of Data Exposure:
- Ensure that Listings metadata does not expose unnecessary personal information.
Anonymization of Transaction Data:
- If transaction logs are public, consider anonymizing buyer details where possible.
User-Controlled Access:
- Allow merchants to set permissions for which entities can view and interact with their inventory.

Performance, Ergonomics, and Compatibility

Performance

Depending on the implementation, the current document might presernt certain performance tradeoffs as a consequence of how it's being implemented.

For example, using standard nonfungibles solutions (like pallet-nfts) might not be the best solution in terms of transactionality, or in terms of resolving certain interfaces that give out composite information about a listing item, due to the nature of how it's designed, but benefits from the extensive nature of handling a generic definition of nonfungible items.

Ergonomics

This proposal improves the quality of life for developers that interact with Kreivo, by allowing them to build experiences that involve representing goods and services that can be exchanged between customers, DAOs and external users (like external chains).

Compatibility

This proposal breaks compatibility of the Payments system. Previously, a payment was arbitrary and involved referring metadata to inform the payer which goods or services were being acquired.

With the introduction of listings, now every payment is associated with acquiring an item. As explained before, a listing item can be anything that is listed within an inventory in the Listings system, and can represent any good, one-time service, order, recurring service, or whatsoever is involved within a transaction between two parties. The metadata is no longer needed, but also, arbitrary payments can no longer be done.

Prior Art and References

Virto APIs: A set of APIs proposed for using Virto Network's (now Kreivo) own infrastructure to provide decentralised services directed toward local merchants.
Pallet Payments: A pallet designed in the context of Virto APIs to handle secure and reversible payments.

Unresolved Questions

Should service contracts (that are billed with scheduled vesting) be included into this specification, or should a separate system be enacted for this purpose? @pandres95

This RFC opens a window to define an RFC that encompasses the changes in the behaviour of the Payments system. This RFC should include, among others:

Charge mechanisms associated to a payment (one-time, recurring, etc.).
Chargebacks and their effects in items already transferred to an user.
Programmable conditions over a payment associated to an item (i.e. fees to the creator of the listing when reselling an item).