# 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 ([e-mail]) |

## 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

## Future Directions and Related Material

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_).

<!-- References -->

[RFC001]: https://hackmd.io/@pandres95/rfc-001-virto-sdk
[Virto APIs]: https://github.com/virto-network/virto-apis
[Pallet Payments]: https://github.com/virto-network/kreivo/tree/master/pallets/payments