Tokenization

The main purpose of the tokenization service is to allow i3Market actors (i.e Marketplace, Data Provider, Data Consumer) to call the I3Market trasury contract methods and interact with the I3Market token flow presented below:

Swagger documentation

The OAS documentation can be accessed here.

Preliminary Informations

Create your Mmarketplace identity on the wallet
If you are using the master-docker-compose, configure the Tokenizer service .env file (MARKETPLACE_ADDRESS value) with the address of the Marketplace that you want to use.
Marketplaces should use the server wallet if they are not requiring any user interaction to sign marketplace transactions.
In I3Market we have ETHERS to pay the gas fee needed to deploy transcations on the blockchain and we have I3M TOKENS to pay a fee for a data transfer.
- In order to call the api of the Tokenizer service and send I3M TOKENS the sender address should have ETHERS in his balance.
- You can query the ETHER balance from the Wallet app and the I3M TOKEN balance from the api/v1/treasury/balances/{address} api.

Use cases

TRANSACTION FLOW

The first use case is the creation and deployment of a signed transaction on the I3M Besu blockchain. Only POST operations (except deploy_signed_transaction) at the Tokenizer endpoints create a transaction object that must be signed and then deployed separately using the flow presented here (because these are the only operations that change the state of the blockchain):

The first step is to create a new raw transaction using on of the POST operations available. After a successful transaction the payload of the response will be a transaction object like this one:
```
{
    "transferId":"68aa8652-6457-5786-81cb-2ee2cc906aa6",
    "transactionObject":{
        "nonce":12,
        "gasLimit":12500000,
        "gasPrice":204695,
        "to":"0x3663f8622526ec82aE571e4265DAd6967dd74260",
        "from":"0x50c0F1E9ACF797A3c12a749634224368ebC1f59A",
        "data":"0x909770870000000000000000000000000000000000000000870000a18943324"
    }
}
```
With this operation, the Marketplace Tokenizer service save in its database the operation with the operation_name (i.e. exchangeIn, exchangeOut, clearingIn, clearingOut, fee-payment) with status UNSIGNED-OPERATION, the address of the user involved, the date and a unique transferID to get this operation at a later time:

TRANSFERID OPERATION STATUS USER DATE

1111 operation_name unsigned_operation address date
Now the raw transaction has to be signed with the I3M wallet. Only the fields contained in the "transactionObject" are used for tor the signing transaction operation. The other parameters are the unique transferId with some information about the operation as the status and the date.
Object to be signed
```
{
    "nonce":12,
    "gasLimit":12500000,
    "gasPrice":204695,
    "to":"0x3663f8622526ec82aE571e4265DAd6967dd74260",
    "from":"0x50c0F1E9ACF797A3c12a749634224368ebC1f59A",
    "data":"0x909770870000000000000000000000000000000000000000870000a18943324"
}
```
The next step is to deploy the signed transaction. Once the Marketplace get the signed raw transaction it can call the deployment endpoint of the tokenization service api/v1/treasury/transactions/deploy-signed-transaction. The response of the request should be a long transaction object with information about the transaction.
When the operation deployment is successful, the Marketplace Tokenizer service updates in its database the operation with other statuses depending on the operation involved, you can check the different processes below.

TRANSFERID	OPERATION	STATUS	USER	DATE
1111	operation_name	unsigned_operation	address	date

You can see in the following image the interaction flow described above:

REGISTER MARKETPLACE: (marketplace VC )

In this use case, we impersonate a Marketplace that wants to register on the I3M platform.

The first step is to call the api/v1/treasury/marketplaces endpoint in the Tokenizer APIs. The address of the marketplace you want to register must be provided in both senderAddress and marketplaceAddress body parameters.
To deploy this transaction to Besu and complete the exchange, the Marketplace have to follow the TRANSACTION FLOW section. Once the operation is completed successfully the new marketplace is added.

EXCHANGE IN: (marketplace VC )

In this operation, the Marketplace sends tokens to the Data Consumer in exchange for Fiat Money which must be paid in advance by the Data Consumer (Fiat payments are outside the scope of the Tokenizer service). The payment in fiat money is managed by the marketplace which must carry out the necessary checks before paying the token fee.

A Data Consumer can exchange fiat money for tokens with a registered Marketplace. More specifically, the Marketplace has to call the exchange-in method once it get the fiat money from the user. In the api/vi1/transactions/exchange-in API request body, the Marketplace has to specify the dataConsumer address and the tokens that it wants to exchange. The successful response is a transaction object with the unique transferID.
To complete and deploy this transaction to Besu and complete the exchange the Marketplace have to follow the TRANSACTION FLOW section.

The Tokenizer save in the database the unsigned operation

TRANSFERID OPERATION STATUS USER DATE

1111 exchange_in unsigned dataConsumerAddress date
When the operation deployment is successful, the Marketplace Tokenizer service updates in its database the operation with status CLOSED:

TRANSFERID OPERATION STATUS USER DATE

1111 exchange_in closed dataConsumerAddress later-date
The operation status can be obtained and evaluated by the marketplace with the api/v1/operations endpoint. An additional check can be done by calling the balance endpoint api/v1/treasury/balances/{address} of the Data Consumer.

TRANSFERID	OPERATION	STATUS	USER	DATE
1111	exchange_in	unsigned	dataConsumerAddress	date

TRANSFERID	OPERATION	STATUS	USER	DATE
1111	exchange_in	closed	dataConsumerAddress	later-date

CLEARING: (marketplace VC )

In this operation, a Marketplace can clear the tokens in its balance distributed by the other Data Marketplaces.

A Marketplace can clear all the token in its balance that belong to other marketplaces calling the clearing API api/v1/operations/clearing on the Tokenizer service; The successful response is a transaction object.

The Tokenizer for each clearing operation follow the steps in the TRANSACTION FLOW section and save the entries in the database.

Marketplace1 DB:

TRANSFERID OPERATION STATUS USER DATE

1111 clearing_out unsigned marketplace2Adr date

2222 clearing_out unsigned marketplace3Adr date

3333 clearing_out unsigned marketplace4Adr date

When the clearing operation is successfully sended.

The Tokenizer updates for each operation the entry in the database.

Marketplace1 DB:

TRANSFERID	OPERATION	STATUS	USER	DATE
1111	clearing_out	unsigned	marketplace2Adr	date
2222	clearing_out	unsigned	marketplace3Adr	date
3333	clearing_out	unsigned	marketplace4Adr	date
1111	clearing_out	open	marketplace2Adr	later-date
2222	clearing_out	open	marketplace3Adr	later-date
3333	clearing_out	open	marketplace4Adr	later-date

If you want to check if the transaction was completed you can also check the balance of the address you have used. The api/v1/treasury/balances/{address} endpoint should return the new balance after the clearing.
As the Tokenizer service of one of the marketplaces involed in the operation receive from the blockchain the EVENT of a requested clearing out, an operation "clearingIn" is saved in its database.

Marketplace2 DB:

TRANSFERID OPERATION STATUS USER DATE

1122 clearing_in open marketplace1Adr date
When a Marketplace owner of the tokens (ex: Marketplace2) pays with fiat money the tokens received, he has to call its Tokenizer api setPaid api/v1/operations/set-paid with its own address in the senderAddress field, the transferId of the clearingIn operation and the transferCode with the Bank transfer identifier of the transaction to keep track of it.
The Marketplace2 Tokenizer when the set-paid operation is successful updates the clearingIn operation as closed by adding a new entry to the database with same transferID and a later date;

Marketplace2 DB:

TRANSFERID OPERATION STATUS USER DATE

1122 clearing_in open marketplace1Adr date

1122 clearing_in closed marketplace1Adr more-later-date

TRANSFERID	OPERATION	STATUS	USER	DATE
1122	clearing_in	open	marketplace1Adr	date

TRANSFERID	OPERATION	STATUS	USER	DATE
1122	clearing_in	open	marketplace1Adr	date
1122	clearing_in	closed	marketplace1Adr	more-later-date

The Tokenizer of the marketplace that requested the clearing, should listen for the clearingIn EVENT and once received successfully can add the closed operation for the same transferId;

Marketplace1 DB:

TRANSFERID	OPERATION	STATUS	USER	DATE
1111	clearing_out	unsigned	marketplace2Adr	date
2222	clearing_out	unsigned	marketplace3Adr	date
3333	clearing_out	unsigned	marketplace4Adr	date
1111	clearing_out	open	marketplace2Adr	later-date
2222	clearing_out	open	marketplace3Adr	later-date
3333	clearing_out	open	marketplace4Adr	later-date
1111	clearing_out	closed	marketplace2Adr	more-later-date

The Marketplace must now have received the money from the marketplace to which the clearing was requested and can check the transfer status of the fiat money with the TransferCode field in the TokenTransfer object;

FEE-PAYMENT: (consumer VC )

A Data Consumer must pay a fee to purchase some data from a data provider. Specifically, it should pay part of the fee to the Community smart contract and part to the Data Provider Marketplace. The Treasury smart contract manages the split of the fee and the sending of the tokens to the parties.

The fee-payment method has to be called before the Data Consumer get the data from the Data Provider. In the api/v1/operations/fee-payment API request body the senderAddress which should be the data consumer, a providerAddress and the tokens that he has have to pay as fee have to be specified. The successful response is a transaction object unique transferID.
The signed raw transaction has to be deployed once the Data Provider receive the data from the Data Provider. To deploy this transaction to Besu and complete the exchange the Marketplace have to follow the TRANSACTION FLOW section.

The Tokenizer save in the database the unsigned operation

TRANSFERID OPERATION STATUS USER DATE

1111 fee_payment unsigned dataConsumerAdr date
When the operation deployment is successful, The Marketplace Tokenizer service updates the operation by add an new entry in the database with same transferID and status as closed:

TRANSFERID OPERATION STATUS USER DATE

1111 fee_payment closed dataConsumerAdr later-date
The operation status can be obtained and evaluated by the marketplace with the api/v1/operations endpoint. An additional check can be done by calling the balance endpoint api/v1/treasury/balances/{address} of the addresses involved.

TRANSFERID	OPERATION	STATUS	USER	DATE
1111	fee_payment	unsigned	dataConsumerAdr	date

TRANSFERID	OPERATION	STATUS	USER	DATE
1111	fee_payment	closed	dataConsumerAdr	later-date

EXCHANGE OUT: (provider VC )

In this operation, a Data Provider can exchange tokens for Fiat Money from a Data Marketplace in the network.

A Marketplace has to call the exchange-out method once it get the fiat money from the user. In the [/transactions/exchange-out] API request body the marketplace need to specify the senderAddress which should be the data provider and the marketplaceAddress with whom it wants to exchange the tokens. The successful response is a transaction object with a unique transferId.
To deploy this transaction to Besu and complete the exchange the Marketplace have to follow the TRANSACTION FLOW section.

The Tokenizer save in the database the unsigned operation

TRANSFERID OPERATION STATUS USER DATE

1111 exchange_out unsigned dataProviderAdr date
The Tokenizer service wait for the blockchain successful operation and update the exchangeOut operation as inProgress:

TRANSFERID OPERATION STATUS USER DATE

1111 exchange_out open dataProviderAdr later-date
the Marketplace now should pay back the token he created and ask the clearing for all the tokens that are not its own. FInally the Marketplace should get the list of the inprogress exchange out operations from the database, and pay back the data providers;

Exchange-out strategy example in the chapter below

TRANSFERID	OPERATION	STATUS	USER	DATE
1111	exchange_out	open	dataProviderAdr	later-date

As soon a Data Provider has been paid with the fiat money, the Marketplace should call the Tokenizer api api/v1/operations/set-paid passing its address as the senderAddress, the transferId of the exhcnageOut operation and the transferCode of the fiat money bank transfer. When this process is completed the exchangeOut operation is updated as closed;

TRANSFERID	OPERATION	STATUS	USER	DATE
1111	exchange_out	unsigned	dataProviderAdr	date
1111	exchange_out	open	dataProviderAdr	later-date
1111	exchange_out	closed	dataProviderAdr	more-later-date

The exchange_out operation status can be checked by the marketplace with the api/v1/operations API.

EXCHANGE-OUT STRATEGY

This is a suggested strategy that each Marketplace should implement in its code. Other strategies can be used in agreement with the network Marketplaces.

REQUIREMENTS:

Set a number variable X as the interval of days that a marketplace collect exchange-out requests.
Set a numeric variable Z as the interval of days in which a marketplace must wait for other marketplaces to pay in fiat money for the tokens sent via clearing

STRATEGY FLOW:

MARKETPLACE ordered steps for Exchange-out operation:

Starting from the first day a marketplace starts operating, in the first X days the Marketplace should collect all the Exchange Out requests from the users (Community);
At the end of X days, the Marketplace asks to exchange the tokens in its balance that belong to other Marketplaces;
Now the Marketplace should wait for other Z days so that all the other Marketplaces can pay with Fiat Money the tokens sent with the clearing operation;
Once the Z days have passed and the fiat money form the clearings are collected, the marketplace can payout the users that in the first X days requested the exchange-out of tokens;
The Marketplace can restart in parallel this flow and collect another round of exchange-out requests at the end of the point 2.

Last update: 2022-12-15
Created: 2022-04-06