| fip | title | status | type | author | created | updated |
|---|---|---|---|---|---|---|
11 |
Add ability to purchase bundled transactions |
Final |
Functionality |
Pawel Mastalerz <[email protected]> |
2020-06-10 |
2021-08-31 |
This FIP implements enhancements to the way bundled transactions are acquired and used. Specifically:
- Adds ability to purchase multiple sets of bundled transactions in single action.
Proposed new actions:
| Action | Endpoint | Description |
|---|---|---|
| addbundles | add_bundled_transactions | Adds bundles of transactions to FIO Address. |
Bundled transactions make it easier for everyday users to interact with the FIO Protocol. Users pay a single annual fee for the FIO Address and get with it enough bundled transactions to cover an average amount of annual interaction with the FIO Chain.
There is one improvement which can further enhanced the usability:
- Users who process more transaction than the annual amount of bundled transactions can either pay a per transaction fee for all additional transactions or renew their FIO Address early, which adds new bundle of transactions and extends FIO Address expiration date. However, heavy users will have to run multiple renewals in sequence. A better approach would be to allow ability to purchase multiple sets of bundled transactions in a single blockchain transaction.
Adds bundles of transactions to FIO Address.
| Parameter | Required | Format | Definition |
|---|---|---|---|
| fio_address | Yes | FIO Address | FIO Address which will receive bundled transactions. |
| bundle_sets | Yes | Int | Number of sets of bundles to add to FIO Address. |
| max_fee | Yes | Positive Int | Maximum amount of SUFs the user is willing to pay for fee. Should be preceded by /get_fee for correct value. |
| tpid | Yes | FIO Address | FIO Address of the entity which generates this transaction. TPID rewards will be paid to this address. Set to empty if not known. |
| actor | Yes | 12 character string | Valid actor of signer |
{
"fio_address": "purse@alice",
"bundle_sets": 1,
"max_fee": 40000000000,
"tpid": "rewards@wallet",
"actor": "aftyershcu22"
}
- Request is validated per Exception handling. Explicitly allowed:
- Adding bundled transactions to FIO Address not owned by actor
- Fee is collected: add_bundled_transactions fee * bundle_sets. Example:
- add_bundled_transactions fee: 40 FIO
- bundle_sets: 2
- Fee charged 80 FIO
- Bundled transaction counter is incremented by number of transactions as currently voted by BPs via submit_bundled_transaction
| Error condition | Trigger | Type | fields:name | fields:value | Error message |
|---|---|---|---|---|---|
| Invalid FIO Address | Invalid FIO Address format or FIO Address not registered. | 400 | "fio_address" | Value sent in, e.g. "purse@alice" | "Invalid FIO Address." |
| FIO Address expired | Supplied FIO Address has expired | 400 | "fio_address" | Value sent in, i.e. "purse@alice" | "FIO Address expired." |
| FIO Domain expired | Domain of supplied FIO Address has expired more than 30 days ago | 400 | "fio_address" | Value sent in, i.e. "purse@alice" | "FIO Domain expired." |
| bundle_sets must be > 0 | bundle_sets is not > 0 | 400 | "bundle_sets" | Value sent in, e.g. "-1" | "Invalid bundle_sets value" |
| Invalid fee value | max_fee format is not valid | 400 | "max_fee" | Value sent in, e.g. "-100" | "Invalid fee value" |
| Insufficient funds to cover fee | Account does not have enough funds to cover fee | 400 | "max_fee" | Value sent in, e.g. "1000000000" | "Insufficient funds to cover fee" |
| Invalid TPID | tpid format is not valid | 400 | "tpid" | Value sent in, e.g. "notvalidfioaddress" | "TPID must be empty or valid FIO address" |
| Fee exceeds maximum | Actual fee is greater than supplied max_fee | 400 | max_fee" | Value sent in, e.g. "1000000000" | "Fee exceeds supplied maximum" |
| Parameter | Format | Definition |
|---|---|---|
| status | String | OK if successful |
| fee_collected | Int | Amount of SUFs collected as fee |
{
"status": "OK",
"fee_collected": 2000000000
}
It may be beneficial to allow set_fio_domain_public to be paid with bundled transactions. However, since this action does not currently collect FIO Address and to support backwards compatibility, a new call (e.g. set_fio_domain_public_btx) would have to be created and co-exist with old call. This may create some confusion for implementing wallets. Therefore, it is not being considered in this FIP, but may be added in the future.
This FIP will be rolled out in separate releases:
- An initial fio.contracts release will include the addbundles action and will be accessible via push_transaction.
- A subsequent fio chain release will include the transfer_tokens_fio_add API endpoints.
- The contract action addbundles was released in fio.contracts v2.3.0.
- The add_bundled_transactions API endpoint released in fio v3.0.0.
No impact on existing functionality, actions or API endpoints.
- Allow set_fio_domain_public to be paid with bundled transaction
- Add ability to transfer FIO tokens using FIO Address and paying with bundled transactions.
"Add ability to transfer FIO tokens using FIO Address and paying with bundled transactions" was initially considered part of this FIP, but was removed, because:
- There is compatibility issue associated with the fact that record_obt requires a transaction ID, which is encrypted client-side, but that transaction ID is not available until token transfer is executed. It would therefore have to be left blank which would cause incompatibilities with wallets which rel;y on that transaction ID being returned in get_obt_data.
- trnsfiopubad allowed for fio_request_id as parameter, but only allowed FIO Address as payee address. This could create issues when wallet developer uses this call to send FIO tokens in response to a FIO Request which contained a different FIO Public Key then associated with the sending FIO Address.
This functionality is now tracked as a separate initiative and will require re-definition to address these issues.
The information about trnsfiopubad is being moved out of the main body of this FIP top this section to be preserved for future consideration.
- FIO token transfer does not currently support the use of bundled transactions. This was primarily, because bundled transactions require a FIO Address and the base FIO token transfer action, trnsfiopubky, transfers tokens using public key. It could be enhanced to allow for optional FIO Address of sender, but in order to maintain backwards compatibility, a new action/end-point is a better option. In addition, it was always envisioned that ability to transfer FIO tokens using FIO Address and combining record_obt_data into the same call was a beneficial feature. Currently if a user wants to send FIO tokens to another user and attach a memo, they have to execute 2 transactions: trnsfiopubky and recordobt.
Transfers FIO tokens and records OBT Data.
| Parameter | Required | Format | Definition |
|---|---|---|---|
| payee_fio_address | Yes | FIO Address | FIO Address of the payee. |
| payer_fio_address | Yes | FIO Address | FIO Address of the payer. |
| amount | Yes | Amount sent in SUFs | Amount of transfer. |
| content | Yes | FIO public key | Encrypted blob. Same as content element of /record_obt_data |
| fio_request_id | Yes | String or empty if no FIO Request ID | ID of FIO Request, if this transfer is in response to a previously received FIO Request. |
| max_fee | Yes | Positive Int | Maximum amount of SUFs the user is willing to pay for fee. Should be preceded by /get_fee for correct value. |
| tpid | Yes | FIO Address | FIO Address of the entity which generates this transaction. TPID rewards will be paid to this address. Set to empty if not known. |
| actor | Yes | 12 character string | Valid actor of signer |
{
"payer_fio_address": "purse@alice",
"payee_fio_address": "crypto@bob",
"amount": 1000000000,
"content": "JhTnxX9ntI9n1eucNuJzHS1/JXeLj+GYmPD1uXG/5PBixQeHg40d4p4yHCm6fxfn7eKzcYFlV2AFrQ7j/kRQJUk5OcvJzZtCYuvIx6snciwhOvYtBlN7MWKavxWV3XGAJHBrQxxcHQGW0rtCZM4KzVYYqXWMzihN6mRGDqxGALc=",
"fio_request_id": "10",
"max_fee": 0,
"tpid": "rewards@wallet",
"actor": "aftyershcu22"
}
- Request is validated per Exception handling
- Fee is collected or bundled transaction deducted
- Funds are transferred to the account associated with the FIO Public Key mapped to the provided Payee FIO Address for chain: FIO, token: FIO. Please note that it is not transferred to the account which owns the Payee FIO Address, although it will often be the same.
- Record OBT transaction is created.
| Error condition | Trigger | Type | fields:name | fields:value | Error message |
|---|---|---|---|---|---|
| Invalid Payee FIO Address | Format of FIO Address not valid, FIO Address does not exist or is not mapped to a valid FIO Public Key. | 400 | "payee_fio_address" | Value sent in, i.e. "purse@alice" | "Payee FIO Address invalid, does not exist or is not mapped to a valid FIO Public Key." |
| Invalid Payer FIO Address | Format of FIO Address not valid or FIO Address does not exist. | 400 | "payer_fio_address" | Value sent in, i.e. "purse@alice" | "Payer FIO Address invalid or does not exist." |
| FIO Address expired | Supplied FIO Address has expired | 400 | "payer_fio_address" | Value sent in, i.e. "purse@alice" | "FIO Address expired." |
| FIO Domain expired | Domain of supplied FIO Address has expired more than 30 days ago | 400 | "payer_fio_address" | Value sent in, i.e. "purse@alice" | "FIO Domain expired." |
| Content exceeds limits | content field is less than min or more than max | 400 | "content" | Value sent in, e.g. "XXX" | "Requires min 64 max 432 size" |
| Invalid fee value | max_fee format is not valid | 400 | "max_fee" | Value sent in, e.g. "-100" | "Invalid fee value" |
| Insufficient funds to cover fee | Account does not have enough funds to cover fee | 400 | "max_fee" | Value sent in, e.g. "1000000000" | "Insufficient funds to cover fee" |
| Invalid TPID | tpid format is not valid | 400 | "tpid" | Value sent in, e.g. "notvalidfioaddress" | "TPID must be empty or valid FIO address" |
| Fee exceeds maximum | Actual fee is greater than supplied max_fee | 400 | max_fee" | Value sent in, e.g. "1000000000" | "Fee exceeds supplied maximum" |
| Not owner of Payer FIO Address | The signer does not own the Payer FIO Address | 403 | Type: invalid_signature |
| Parameter | Format | Definition |
|---|---|---|
| status | String | OK if successful |
| fee_collected | Int | Amount of SUFs collected as fee |
{
"status": "OK",
"fee_collected": 2000000000
}
This call combines 2 most expensive calls on the FIO Chain: trnsfiopubky and recordobt. It was initially thought that trnsfiopubky will not be creating a new account as the Payee already has a FIO Address, but the Payee's FIO Address mapping could contain a brand new FIO Public Key which is not yet associated with a new account, as there is no validation in addaddress.
However, when the user does not enter any memo, one may argue that recordobt should not be executed and therefore the fee should be lower.
- Allow for content to be empty and if it is, do not execute recordobt and charge a lower fee. This approach would not be consistent with our fee standard. We would need to have 2 fees for same action, which will be confusing.
- Create a new action for token transfer with memo.