Enabling Arbitrary Programmability of HTS Tokens

[mshakeg]

Introduction

This discussion aims to propose an integration of the Hedera Token Service (HTS) with the Hedera Smart Contract Service (HSCS) to allow for arbitrary programmability of HTS tokens. This integration will allow developers to build unique functionality into their HTS tokens that can be triggered before and after various native HTS actions on tokens such as transfers, mints, burns, etc.

Problem Statement

Currently, HTS tokens are limited in their programmability as they only allow for certain constraints to be configured and managed, such as freezing/unfreezing accounts, granting/revoking KYC, and token fees. This limits the potential use cases for HTS tokens and prevents developers from building applications that require custom programmability on the Hedera network. By integrating the HTS with the HSCS, developers will be able to build custom functionality into their HTS tokens, expanding the potential use cases for HTS and the Hedera network as a whole.

Proposed Solution

The proposed solution is to add a new solidity interface called IHERC20 that will allow developers to define custom pre and post modifier functions for their HTS tokens. These modifier functions can be triggered before and after various actions on a given token, such as transfers, mints, burns, etc provided the token has a set HERC20 contract that implements the IHERC20 interface. The modifier functions will receive an actionCode that indicates the type of action that triggered the function(e.g. transfer, mint, burn) and a second parameter actionParams that encodes information about the action, such as the account that initiated the action, the amount transferred, minted, or burned, etc.

interface IHERC20 {

  // if an HTS token's preModifier is defined it is executed before an HTS action
  function preModifier(uint8 actionCode, bytes actionParams) external returns (bool success);

  // if an HTS token's postModifier is defined it is executed after HTS action
  function postModifier(uint8 actionCode, bytes actionParams) external returns (bool success);

}

A developer can implement a contract that inherits the IHERC20 interface and must implement at least one function either the preModifier or postModifier, they can then deploy the contract and when creating or updating an HTS token can set/overwrite that token's HERC20 contractId.

When a token's HERC20 contractId is set or updated the preModifier and postModifier functions on the HERC20 should be pre-tested for validation on the interface in addition to confirming what actions the HERC20 contract's modifers support to prevent unnecessary execution for actions that are not supported, this can be done by defining a range of actionCodes for the initial test. For example if actionCode 255 is for testing support on transfers and actionCode 1 is the corresponding actual actionCode for transfers. If {pre|post}Modifier(255, ...) returns true in the pre-test then {pre|post}Modifier() should be executed accordingly on any transfer i.e. actionCode 1.

Benefits

• Increased programmability of HTS tokens - equivalent to the programmability of ERC20 tokens.
• Increased potential use cases for HTS tokens - think of the multiplicity of unique ERC20 tokens that cannot be implemented using the HTS due to lack of programmability.

Drawbacks

• Potential for security risks if poorly written modifier functions are used.
• Throughput reduction for HTS tokens that specify an HERC20 contract that implements modifiers at least for actions that require {pre|post}Modifier execution.
  • The HTS is capable of 10k TPS and the HSCS is capable of 15m gas/s (~200 simple ERC20 transfers per second which is likely also the maximum number of simple modifers that can be executed, i.e. more complex modifiers will obviously require more gas)

Conclusion

The proposed integration of the HTS with the HSCS to allow for arbitrary programmability of HTS tokens has the potential to greatly expand the use cases for HTS tokens and the Hedera network as a whole.

[mgarbs]

Question:
How is this different from HIP-206 Hedera Token Service Precompiled Contract for Hedera SmartContract Service ?

As a smart contract developer, I want to be able to transfer, mint, burn, associate, and dissociate smart contract tokens through solidity contract calls.

As a smart contract developer, I want my smart contract to be able to transfer, mint, burn, associate, and dissociate tokens where authorization is granted because my smart contract initiated the call and without any other signatures.

[mshakeg]

Hi @mgarbs , HIP-206 does not allow arbitrary programmability of HTS tokens, it only enables smart contracts to:

transfer, mint, burn, associate, and dissociate smart contract tokens through solidity contract calls

However, what I'm proposing is as the discussion is titled "enabling arbitrary programmability of HTS tokens" :) So basically you enable developers to do pre/post-checks or pre/post-state changes(hence the name {pre|post}Modifier as it behaves similarly to solidity function modifiers) on any HTS action. So for example a developer could enforce a check that an account can only transfer a token if it passes a check(for example that check could be only 1 transfer per account per day or a maximum of x amount of tokens can be transferred in a given day). Now when an account does an HTS token transfer then if that token has pre/post-modifiers specified that are enabled for token transfers then those modifiers are executed accordingly and if they return success=false or revert then the HTS token transfer fails.

Using a HERC20 smart contract to enable such programmability allows for the HERC20 contract to manage its own internal state(to for example track the last token transfer by an account or the amount of said token transferred in the last day) and also access other smart contracts if required.

[mshakeg]

Hey @Nana-EC I finally got around to detailing the idea I initially proposed to you here.

It's focused only on part of what I initially proposed, but I'd much appreciate your feedback if possible.

[mgarbs]

I think 514 enables the remaining functionality of HTS for smart contracts

User stories
As a smart contract developer, I would like to retrieve fungible token metadata details through a precompile contract.

As a smart contract developer, I would like to retrieve non-fungible token metadata details through a precompile contract.

As a smart contract developer, I would like to modify token entity properties through a precompile contract.

As a smart contract developer, I would like to modify token KYC permissions through a precompile contract.

As a smart contract developer, I would like to retrieve token KYC status through a precompile contract.

As a smart contract developer, I would like to modify token Freeze state through a precompile contract.

As a smart contract developer, I would like to retrieve token Freeze status through a precompile contract.

As a smart contract developer, I would like to modify token Pause state through a precompile contract.

As a smart contract developer, I would like to retrieve token Pause status through a precompile contract.

As a smart contract developer, I would like to retrieve token fee properties through a precompile contract.

As a smart contract developer, I would like to retrieve token key properties through a precompile contract.

As a smart contract developer, I would like to delete a token through a precompile contract.

As a smart contract developer, I would like to wipe an amount of fungible tokens from an account balance through a precompile contract.

As a smart contract developer, I would like to wipe an amount of non-fungible tokens from an account balance through a precompile contract.

[mshakeg]

@mgarbs HIP-514 does NOT address:

Enabling Arbitrary Programmability of HTS Tokens

I'm not sure how better to explain, but perhaps a real-world example would be better. For example, the _afterTokenTransfer internal hook function in the OpenZeppelin Governance Token is called after a token transfer and performs custom developer-defined logic, and in the context of the OpenZeppelin Governance Token updates the vote weight of the sender and recipient.

This arbitrary programmability is not currently possible with HTS tokens, and the proposed {pre|post}Modifier is one way of enabling this.

[Nana-EC]

Thanks @mshakeg.
Interesting concept. I get the overall idea.
Basically since you can't modify an HTS tokens core functions with code you are trying to provide it?
There's an argument to say you can essentially add the pre and post items in your implementing contracts function but I guess this provides a way to group the logic and make it referable.

Need to read over it one or two more times to get a clear understanding but to help could you please clarify the following

1. What can pre and post hooks do? Is it indeed anything you can code into a solidity function? Does it include or exclude other HTS precompile method executions?
2. Can you provide maybe 2-3 more examples of how this might play out to get a better understanding of normal usage. Also highlight an example of something you want to do but can't do in the current network architecture.
3. How does the action code assignment work? Is it pre assigned and custom to every contract and by who or is there a preset allocation across all contracts - set by who? I read it as the latter but maybe could you give examples of actionCode and it's range
4. For actionParams will the params be predictable or are the value format be configureable by the user or the contract?
5. Who is responsible for the connect on execution? Are you saying when an HTS precompile function is executed that the network should check if the contract has a pre / post function and then execute it on behalf of the user/contract. Or is this a hook in by solidity. Might need to read more on this.

Also can you elaborate on the below. It's unclear to me how and when this testing is occurring. Is it at deployment time or ahead?

When a token's HERC20 contractId is set or updated the preModifier and postModifier functions on the HERC20 should be pre-tested for validation on the interface in addition to confirming what actions the HERC20 contract's modifiers support to prevent unnecessary execution for actions that are not supported, this can be done by defining a range of actionCodes for the initial test.

[mshakeg]

Thanks for the reply @Nana-EC

Basically since you can't modify an HTS tokens core functions with code you are trying to provide it?

That is correct.

There's an argument to say you can essentially add the pre and post items in your implementing contracts function but I guess this provides a way to group the logic and make it referable.

My proposal doesn't necessarily contradict this as indicated in my Simple Solidity Example below. However, the pre and post modifiers should not be limited to execution only for contract transactions/calls, but should also be executed if any of the standard HTS transactions are attempted.

What can pre and post hooks do? Is it indeed anything you can code into a solidity function? Does it include or exclude other HTS precompile method executions?

It can indeed do anything you can code into a solidity function including the same action that triggered the initial modifier execution, this will basically result in a kind of recursive behaviour. Take for example a {pre|post}Modifier which awards the recipient of a transfer 1% of an HTS transfer from the treasury, the execution trace would look something like the following assuming this 1% bonus logic is defined in the preModifier:

• sign and submit a TransferTransaction for x amount of token
• since the token's HERC20's preModifier function supports HTS transfers it is executed before the logic for the TransferTransaction
• the preModifier then attempts another HTS transfer to award a 1% bonus to the recipient from the treasury, this in turn triggers a 2nd preModifier to be executed, however, since this 2nd preModifier is able to check that the sender of this HTS transfer is the treasury it simply returns success=true without awarding another 1% bonus, i.e. recursion stops at the 2nd preModifier.
• now we're back in the context of the 1st preModifier which proceeds with its logic which simply returns success=true
• now the normal logic for handling the TransferTransaction of x amount is executed
• and since the postModifier does not support HTS transfers there's no need to execute it and the transaction is complete.
• Obviously, if it reverts/fails at any stage in either the {pre|post}Modifier or due to any existing logic for the TransferTransaction(e.g. insufficient balance, or recipient not associated with the token, etc) then all fees will still be paid for any gas incurred from the execution of the {pre|post}Modifier in addition to the transaction cost for a TransferTransaction.

Can you provide maybe 2-3 more examples of how this might play out to get a better understanding of normal usage. Also, highlight an example of something you want to do but can't do in the current network architecture.

I've given the following solidity code example which is a bit silly but gives an idea of how this can be useful in enabling HTS token programmability equivalent to what's possible on the EVM. I've also previously explained the OpenZeppelin Governance Token which has an _afterTokenTransfer internal hook function that is executed after an ERC20 transfer and has logic to update vote weight for the sender and recipient. This kind of programmability isn't possible directly with HTS token transfers, but can be emulated by having a smart contract custody the HTS tokens and hence in order to do an HTS transfer the smart contract has to be invoked to prevent the circumvention of the pre/post-modifiers/checks. This would require the smart contract to expose a function that can be invoked to do the transfer of the custodied tokens and directly invoke pre/post modifiers/checks within that smart contract tx/call. This works, however is non-ideal as it breaks native HTS asset support, as for example you now have to do a contract tx/call for something like an HTS transfer, instead of normally transferring your HTS asset in your preferred native Hedera wallet which executes a TransferTransaction.

How does the action code assignment work? Is it pre-assigned and custom to every contract and by who or is there a preset allocation across all contracts - set by who? I read it as the latter but maybe could you give examples of actionCode and its range

It is indeed the latter, specifically, the action codes would be set by Hedera. An alternative to using actionCodes would be to have a pre|post modifer function for every HTS action {pre|post}{Action} e.g. {pre|post}Mint, {pre|post}Burn or {pre|post}Transfer, etc. I don't really mind it either way.

For actionParams will the params be predictable or are the value format be configurable by the user or the contract?

Similarly to the actionCodes the actionParams encoding format will be determined by Hedera. And if using the alternative to actionCodes as mentioned above {pre|post}{Action} the actionParams bytes can be replaced with a custom {Action}Params struct e.g. MintParams for {pre|post}Mint, BurnParams for {pre|post}Burn or TransferParams for {pre|post}Transfer as follows:

function preMint(MintParams memory mintParams) external returns (bool success);
function preBurn(BurnParams memory burnParams) external returns (bool success);
function preTransfer(TransferParams memory transferParams) external returns (bool success);

// and similarly for the post{Action} function modifiers

Who is responsible for the connect on execution? Are you saying when an HTS precompile function is executed that the network should check if the contract has a pre / post function and then execute it on behalf of the user/contract. Or is this a hook in by solidity. Might need to read more on this.

Also can you elaborate on the below? It's unclear to me how and when this testing is occurring. Is it at deployment time or ahead?

These 2 questions are closely linked, so I'll answer them both in one go. As previously mentioned the execution of the {pre|post}Modifier functions are not limited to execution within contract transactions/calls, and yes the network would test an HERC20 contract for its HTS action support whenever a token is created or updated provided the HERC20 contract is set or in the case of a token update has changed or perhaps a retest HERC20 request can be implemented to force a retest on a token's specified HERC20 contract. Now that the HERC20 contract has been tested and its HTS actions support has been determined for both its preModifier and postModifier functions, whenever a HTS action is triggered that the {pre|post}Modifier functions support then the node/network executes that modifier accordingly.

Simple Solidity Example

Note this example has the HERC20 contract to be the same contract that creates the token i.e. the HODLToken contract. However, it doesn't necessarily have to work like this. You could deploy an HERC20 contract at contract id 0.0.x and have multiple tokens reference that same HERC20 contract when the token/s are created or updated either programmatically within smart contracts or via the sdk's TokenCreateTransaction or TokenUpdateTransaction respectively.

// SPDX-License-Identifier: GPL-2.0-or-later
pragma solidity ^0.8.0;

// predefined actionCode values
library ActionCodes {
  uint8 internal constant TRANSFER = 1;
  uint8 internal constant TRANSFER_TEST_SUPPORT = 255;
  // ... other HTS action codes(for example mints, burns, etc) and their corresponding {ACTION}_TEST_SUPPORT codes go here
}

interface IHERC20 {

  // if an HTS token's preModifier is defined and functional for a given HTS action then it is executed before that HTS action
  function preModifier(uint8 actionCode, bytes memory actionParams) external returns (bool success);

  // if an HTS token's postModifier is defined and functional for a given HTS action then it is executed after that HTS action
  function postModifier(uint8 actionCode, bytes memory actionParams) external returns (bool success);

}

contract HODLToken is IHERC20 {

    uint64 public constant CERTIFICATION_COST = 100e8; // Defines the HODLer certification cost as 100e8 tinybar or 100 HBAR
    uint64 public constant MAX_DAILY_TRANSFER = 1_000; // Defines the max daily transfer as 1,000 minor units

    uint64 public currentDayTransfer; // Stores the current day's token transfer
    uint32 public lastUnixDay;  // Stores the last unix day

    mapping(address => bool) public certifiedHODLer;  // Mapping of certified HODLers

    address public immutable hodlHtsTokenId; // the HTS tokenId created by an instance of the HODLToken contract

    // ERC20 Transfer event; emit this in the postModifier for the HTS transfer action
    event Transfer(address from, address to, uint256 value);

    // Constructor that creates the token and sets the HERC20 contract to the HODLToken contract
    constructor() {
        address herc20 = address(this);
        // in this case set the HERC20 contract for the token that is created below to *this* contract
        hodlHtsTokenId = createToken(herc20); // create the "HODL" HTS token
    }

    function createToken(address _herc20) internal returns (address createdTokenAddress) {
        // calls the HederaTokenService.createFungibleToken precompile function to create an HTS token
        // requires the IHederaTokenService.HederaToken struct passed to HederaTokenService.createFungibleToken to be extended to allow for the HERC20 contract to be set for the created token
    }

    // ... other functions beyond the IHERC20 modifier function can be implemented for the HODLToken such as the following requestCertification() function

    // Function to request certification from the HODLToken contract
    function requestCertification() external payable {

        require(msg.value >= CERTIFICATION_COST, "INSUFFICIENT_PAID");
        // makes the sender as certified HODLer
        certifiedHODLer[msg.sender] = true;

    }

    function preModifier(uint8 actionCode, bytes memory actionParams) external returns (bool success) {

        // pre-tests to test actionCode support
        // the pre-tests are only executed initially in 2 circumstances
        // 1st when a token is created and the HERC20 contract is set for the token
        // 2nd when a token's HERC20 contract is updated
        if (actionCode == ActionCodes.TRANSFER_TEST_SUPPORT) {
            // preModifier supports transfer & hence execute preModifier before any HTS transfer
            return true;
        }

        if (actionCode == ActionCodes.TRANSFER) {
            uint32 currentUnixDay = uint32(block.timestamp % 86_400);

            // it's a new day; reset currentDayTransfer back to 0 and return true i.e. proceed with the HTS transfer
            if (lastUnixDay < currentUnixDay) {
                lastUnixDay = currentUnixDay;
                currentDayTransfer = 0;
                return true;
            }

            TransferParams memory transferParams = decodeTransferParams(actionParams);

            currentDayTransfer += transferParams.amount;

            bool isRecipientCertifiedHODLer = certifiedHODLer[transferParams.recipient];

            if (!isRecipientCertifiedHODLer || currentDayTransfer > MAX_DAILY_TRANSFER) {

                // we don't want to allow HTS transfers of more than the MAX_DAILY_TRANSFER or if recipient is not a certified HODLer
                // to achieve this we can either:
                // return false and preserve any state changes if desired for whatever reason OR
                // revert to also not allow the HTS transfer but also undo any state changes

                // in this example it would be more appropriate to revert
                revert("NOT_CERT || >MAX_DAILY_TRANSFER");

            }

        }

        // default return value of true to allow the HTS transfer to proceed if it reaches this pointing without returning or reverting elsewhere in the modifier
        return true;

    }

    function postModifier(uint8 actionCode, bytes memory actionParams) external returns (bool success) {

        if (actionCode == ActionCodes.TRANSFER_TEST_SUPPORT) {
            // postModifier supports transfer & hence execute postModifier after any HTS transfer
            return true;
        }

        if (actionCode == ActionCodes.TRANSFER) {

            TransferParams memory transferParams = decodeTransferParams(actionParams);

            // after a successful HTS transfer emit the ERC20 Transfer event
            // developers may want to do this to be able to index HTS token transfers as ERC20/721 Transfer events in their subgraphs
            // the current behaviour of an HTS token transfer does not emit an event and emitting an event in a postModifier as done here is one way of enabling this
            emit Transfer(transferParams.sender, transferParams.recipient, transferParams.amount);

        }

    }

    struct TransferParams {
        address token;
        address origin;
        address sender;
        address recipient;
        uint64 amount;
    }

    function decodeTransferParams(bytes memory transferParamsEncoded) internal pure returns(TransferParams memory transferParams) {
        (address token, address origin, address sender, address recipient, uint64 amount) = abi.decode(transferParamsEncoded, (address, address, address, address, uint64));

        transferParams  = TransferParams({
            token: token,
            origin: origin,
            sender: sender,
            recipient: recipient,
            amount: amount
        });

    }

    // ... other decode{Action}Params functions for supported actions can be defined here

    // note the encoding of actionParams is predefined and hence the decode{Action}Params functions will basically be identical across all HERC20 contracts
    // to avoid the repetition of defining the decode{Action}Params functions in every instance of a HERC20 contract a common library that exposes those functions can be deployed to a known contractId
    // which developers can invoke to decode their actionParams for a given decode{Action}Params function.
}

[mshakeg]

Hi @Nana-EC , I just wanted to check back with you on whether you've had a chance to take a look at my reply.

I've also proposed another idea for increased throughput of the HSCS. I'd appreciate feedback from you or other core engineers on that idea if possible. It isn't an improvement urgently required at current HSCS utilisation, but it's likely a simple enough ask to make it worth implementing preemptively. I noticed that this blog post strangely did not mention parallelization as a solution for improving performance, but instead suggested "compiling frequently used contracts into Java bytecode". However, if I had to guess this is a greater ask technically, in addition, the performance increase from this solution would likely be only marginal compared to parallelization.

[Nana-EC]

Hey @mshakeg sorry, took a while to get back. Will review. shortly and revert.
Thanks in advance for answering the questions.

[mgarbs]

I find this discussion quite interesting, and I would like to learn more about the integration process. Could you provide a flow diagram of how this integration would work with our existing services?

Additionally, you mentioned potential throughput reduction for HTS tokens that specify an HERC20 contract that implements modifiers, but the HTS is capable of 10k TPS. Can you explain how we could maintain this high throughput while integrating smart contracts with the HTS?

[mshakeg]

Hi @mgarbs the HERC20 contract would be specified for fungible HTS tokens and the HERC721 contract would be for non-fungible HTS tokens, but all else would be identical.

Throughput would only affect HTS tokens that specify HERC{20|721} contracts and the exact throughput would depend on the gas requirements for the execution of the {pre|post}Modifiers, so for example say the network is ONLY processing HTS transfers for tokens that implement {pre|post}Modifers where the total gas cost per HTS transfer transaction for the execution of these modifiers averages to 150k gas. Given the current gas limit of 15m gas/s, the network would be able to process 100 HTS transfers(that implement modifiers) per second. To increase the throughput you'd have to increase the effective gas limit beyond 15m gas/s, and one way of doing this would be parallel execution of HSCS transactions. Say for example 16 threads were allocated for parallel HSCS transaction execution, then with each thread handling 15m gas/s and and in the case that all threads are being fully utilised the node is effectively handling 15m gas/s * 16 = 240m gas/s; which translates to 1600 HTS transfers(that implement modifiers) per second; this is obviously a best case where all transactions are distributed equally amongst all threads.

The following flow chart shows both the flow for HERC initialisation for HTS tokens and the flow for {pre|post}Modifier execution on HTS transactions.

[shemnon]

Lots of error handling questions:

• How do we ensure that a pre handler exists on a registered contract?
• For "HERC has a preModifier that supports the action" how do we figure that out? At contract registration, at each call?
• What if the handler reverts instead of returning false?
• What if the hander is deleted?
• What if the handler is deleted for not paying state rent?

Also, I think the design can be simplified.

For the contract it has only one function function actionValidator(int64 hederaFunctionality, address hederaId, bytes memory actionParams) external returns (int64 returnCode). hederaFunctionality is the operation (such as TokenMint), hederaId is the EVM address form of the object (such as token ID) and the return is a Response Code - where anything other than SUCCESS is a failure to be bubbled up, possibly limited to a shorter valid list for both functionality and return code. The actionParams would vary per functionality, so we would definetly want to short-list the supported functionality.

On the hedera side perhaps we register handler addresses per functionality, so every operation doesn't have to go through the EVM. there would be a quick null check and if not null a check against registered function types (with various tricks based on size).

[mshakeg]

Hey @shemnon thanks for the feedback.

I think I've answered some of your questions to some extent in some of my other replies, so I'll quote myself where possible.

---

How do we ensure that a pre handler exists on a registered contract?

For "HERC has a preModifier that supports the action" how do we figure that out? At contract registration, at each call?

I think both points are answered in the following quote replying to Nana:

the network would test an HERC20 contract for its HTS action support whenever a token is created or updated provided the HERC20 contract is set or in the case of a token update has changed or perhaps a retest HERC20 request can be implemented to force a retest on a token's specified HERC20 contract. Now that the HERC20 contract has been tested and its HTS actions support has been determined for both its preModifier and postModifier functions, whenever a HTS action is triggered that the {pre|post}Modifier functions support then the node/network executes that modifier accordingly.

If an HERC contract is specified when creating or updating a token that does not implement the HERC interface i.e. does not implement the {pre|post}Modifier functions then the transaction either fails or the HERC contract is set to null(i.e. interpret it as the token does not have an HERC contract); though I think failing would be better.

---

What if the handler reverts instead of returning false?

Quote from reply to mgarbs:

modifiers are executed accordingly and if they return success=false or revert then the HTS {action} fails.

Quote from reply to nana:

if it reverts/fails at any stage in either the {pre|post}Modifier or due to any existing logic for the {Action}(e.g. insufficient balance, or recipient not associated with the token, etc) then all fees will still be paid

Also in the Simple Solidity Example I left the following comment in the preModifier:

// we don't want to allow HTS transfers of more than the MAX_DAILY_TRANSFER or if recipient is not a certified HODLer
// to achieve this we can either:
// return false and preserve any state changes if desired for whatever reason OR
// revert to also not allow the HTS transfer but also undo any state changes

Based on your actionValidator proposal which is more refined the behaviour would instead be: a tx fails if SUCCESS is NOT returned; i.e. either the actionValidator does an evm revert or returns other than SUCCESS, and in the case of the latter an evm revert would be called to undo any state changes.

So evm state changes are only allowed if SUCCESS is returned.

---

What if the hander is deleted?

What if the handler is deleted for not paying state rent?

I think there should be a tightly coupled one-to-one relationship between HTS tokens and HERC contracts i.e. an HERC contract can only be bound to a single HTS token and vice versa, such that both the HERC contract and HTS token will share at least one account that will have to pay for rent, and if there is not sufficient HBAR such that either the HERC contract or the HTS token will be deleted then BOTH will be deleted.

Additionally, this one-to-one coupling will enhance parallel tx execution if it ever gets implemented, as there's no possibility of multiple tokens pointing to the same HERC contract requiring transactions for tokens that point to the same HERC contract to be executed serially.

---

On the hedera side perhaps we register handler addresses per functionality, so every operation doesn't have to go through the EVM. there would be a quick null check and if not null a check against registered function types (with various tricks based on size).

That's more or less what I had in mind and tried to articulate in my other replies.

---

For the contract it has only one function function actionValidator(int64 hederaFunctionality, address hederaId, bytes memory actionParams) external returns (int64 returnCode).

As previously mentioned I agree with this actionValidator design. I did however want to clarify if the actionValidator function should be called pre or post ACTION? Calling it pre-action execution makes the most sense to me as it allows early failure of a transaction that might have only failed in the postModifier.

---

[shemnon]

If an HERC contract is specified when creating or updating a token that does not implement the HERC interface i.e. does not implement the {pre|post}Modifier functions then the transaction either fails or the HERC contract is set to null(i.e. interpret it as the token does not have an HERC contract); though I think failing would be better.

Specifically, what's the mechanism? Based on what I know about EVM there is no way to guarantee this. EIC-820 is collaborative at best and throw in proxy/upgradable contracts in the mix and the introspection becomes worse. We can do a best effort but there will always be ways the contracts become or start off as irreparably broken and can pass whatever first-pass check we do. So the process needs to keep this in mind.

Specifically if a contract is set for an action only a ABI encoded SUCCESS result will be required, and any other result is rejectec, this makes it anti-fragile to these setup failures.

What if the hander is deleted?

What if the handler is deleted for not paying state rent?

think there should be a tightly coupled one-to-one relationship between HTS tokens and HERC contracts i.e. an HERC contract can only be bound to a single HTS token and vice versa, such that both the HERC contract and HTS token will share at least one account that will have to pay for rent, and if there is not sufficient HBAR such that either the HERC contract or the HTS token will be deleted then BOTH will be deleted.

Additionally, this one-to-one coupling will enhance parallel tx execution if it ever gets implemented, as there's no possibility of multiple tokens pointing to the same HERC contract requiring transactions for tokens that point to the same HERC contract to be executed serially.

We need to be resilient to these presumptions handling. Error cases may arise where there is not a one-to-one relationship between HTS and HERC. (a) bugs will happen and (b) it's an inefficient model. Supporting a many-to-many model will result in cost savings for users.

Consider a "bankers hours" approval contract. Not only do they need to handle the hours of the day, they may need to alter holidays for things like the death of a Monarch or their coronation (a bank holiday that is not predictable), or hours may need to be adjusted for daylight savings time. Having to update every single bankers hours contract is (a) expensive and (b) presents multiple points of failure, what if one gets missed and allows transactions that were not permitted per regulatory closings?

As previously mentioned I agree with this actionValidator design. I did however want to clarify if the actionValidator function should be called pre or post ACTION? Calling it pre-action execution makes the most sense to me as it allows early failure of a transaction that might have only failed in the postModifier.

I'm thinking pre-modifier, but would be open to adding post with a good use case. We could write in that the side effects of a success validation will only commit if the approved functionality commits, so you would do your post implicitly. And we could guarantee all rejects will commit their side effects. But it gets complicated if we allow multiple hooks per functionality, which is a strong argument for only one hook per functionality, and the users can aggregate in their own deployed contract. So one to many, one contract can service may hooks but each hedera object+functionality has only one hook.

[mshakeg]

Specifically, what's the mechanism? Based on what I know about EVM there is no way to guarantee this. EIC-820 is collaborative at best and throw in proxy/upgradable contracts in the mix and the introspection becomes worse. We can do a best effort but there will always be ways the contracts become or start off as irreparably broken and can pass whatever first-pass check we do. So the process needs to keep this in mind.
Specifically if a contract is set for an action only a ABI encoded SUCCESS result will be required, and any other result is rejectec, this makes it anti-fragile to these setup failures.

I haven't heard of EIP-820 prior, but I don't really see the point of explicit and repeated interface introspection since if an HERC contract is specified it can be assumed that the HERC contract implements the actionValidator function. Then the HTS actions supported by the HERC can be tested to avoid unnecessary modifier(i.e. actionValidator) execution on unsupported actions. If for whatever reason the HERC contract does NOT implement an actionValidatorfunction then the action support test will fail which will indicate no action support. The onus will be on developers to test their new/upgraded HERC contract before deploying/upgrading it.

---

Error cases may arise where there is not a one-to-one relationship between HTS and HERC.

I don't follow; how would these error cases arise if a one-to-one relationship is an enforced constraint?

Supporting a many-to-many model will result in cost savings for users.

What would the point be in having an HTS token point to multiple HERC contracts simultaneously? Would that entail the execution of each HERC contract's modifier in a specified sequence provided a given HERC contract supports a given HTS action.

Also, can an HTS token point to an HERC contract that it has no affiliation with(i.e. does not share at least one account that is responsible for paying rent of both the HTS token and HERC contract)? I don't think this should be allowed as it complicates the discussion of rent.

---

I don't really follow your "bankers hours" approval contract example, a one to one relationship between HTS tokens and HERC contracts does NOT necessitate:

Having to update every single bankers hours contract is (a) expensive and (b) presents multiple points of failure, what if one gets missed and allows transactions that were not permitted per regulatory closings?

You can have N HTS tokens with each pointing to its own distinct 1 of N HERC contract with all of these N HERC contracts pointing to the same "bankers hours" approval contract, and only that single "bankers hours" approval contract needs to be updated.

[shemnon]

If for whatever reason the HERC contract does NOT implement an actionValidatorfunction then the action support test will fail which will indicate no action support.

That is what I think is underspecified. When a HERC is set on an action does hedera send a test transaction? With a new hedera functionality to test it?

Error cases may arise where there is not a one-to-one relationship between HTS and HERC.

I don't follow; how would these error cases arise if a one-to-one relationship is an enforced constraint?

Based on your comments further down it looks like you are not proposing what I mean by one to one. I.e. One HERC contract can service multiple tokens. So what needs to be specified is how things are handled if something like the HERC contract being deleted happens. So we likely don't want to gate token admin functions on an HERC approval, or at least the admin function that can set and unset HERCs. Otherwise we can wedge the token and require a council approved irregular state change.

So when I say one-to-one in this context, I mean one HERC contract (0.0.4444444) can only ever serve one token (0.0.555555), and vice versa.

What would the point be in having an HTS token point to multiple HERC contracts simultaneously? Would that entail the execution of each HERC contract's modifier in a specified sequence provided a given HERC contract supports a given HTS action.

That's what many-to-many would provide. One HERC enforces business hours, one may enforce a blocklist on transaction size limits. A token may put both HERCs on transfer to compose a "weekdays only, and no more than $100" rule. and other contracts may just use the $100 limit and others just the weekdays restriction.

Also, can an HTS token point to an HERC contract that it has no affiliation with(i.e. does not share at least one account that is responsible for paying rent of both the HTS token and HERC contract)? I don't think this should be allowed as it complicates the discussion of rent.

That's the error case that comes up with one HERC serving multiple clients. We could impose the requirement their auto_renew_account_id to be the same, but what happens when the account ids get changed after connecting them. Do we add a validation hook preventing that from changing while associated?

I think the cleaner solution is jus to require that if a HERC is set on an object's functionality that the check has to succeed or it all fails. Check returns an error code? failure. Contract reverts? Failure. Contract has been deleted? also failure. Contract is actually a consensus topic? Believe it or not, straight to failure. Plus a notice in the logs to tell devops we have a consistency problem.

[mshakeg]

When a HERC is set on an action does hedera send a test transaction? With a new hedera functionality to test it?

I tried to explain this in the Simple Solidity Example using {ACTION}_TEST_SUPPORT codes. However, using the your actionValidator function hedera can test action support using the same action code but with no actionParams bytes i.e. actionParams.length == 0, for example, an actionValidator that only supports one token(e.g. 0.0.555555) and specifically only supports the transfer action could be implemented something as follows:

library HederaFunctionality {
  int64 internal constant CryptoTransfer = 1;
  int64 internal constant TokenMint = 65;
}

library HederaResponseCodes {
  int64 internal constant SUCCESS = 22;
}

function actionValidator(int64 hederaFunctionality, address hederaId, bytes memory actionParams) external returns (int64 returnCode) {

    address supportedToken = address(555555);
    require(hederaId == supportedToken, "TOKEN_NOT_SUPPORTED");

    bool isActionTest = actionParams.length == 0;

    if (isActionTest) {
      if (hederaFunctionality == HederaFunctionality.CryptoTransfer) {
        return HederaResponseCodesLib.SUCCESS;
      }

      // no other HederaFunctionality is supported so either revert or return default(i.e. 0) to indicate no support for other actions
      return returnCode;

    }

    if (hederaFunctionality == HederaFunctionality.CryptoTransfer) {
      // execute arbitrary logic pre CryptoTransfer execution then return SUCCESS, or if failure then revert or return !SUCCESS response code
      return HederaResponseCodesLib.SUCCESS;
    }

    if (hederaFunctionality == HederaFunctionality.TokenMint) {
      // this block is useless and will never be reached since the above "isActionTest" block does NOT return SUCCESS on TokenMint and hence the actionValidator will never be called on a TokenMint
    }
}

---

Based on your comments further down it looks like you are not proposing what I mean by one-to-one. I.e. One HERC contract can service multiple tokens.

Ah, I misunderstood what you meant by one-to-one, though I would say "One HERC contract can service multiple tokens"(and a token can only point to one HERC contract) is a many-to-one relationship.

So what needs to be specified is how things are handled if something like the HERC contract being deleted happens.

We could impose the requirement their auto_renew_account_id to be the same, but what happens when the account ids get changed after connecting them. Do we add a validation hook preventing that from changing while associated?

I don't think that the HERC contract should ever be deleted while HTS tokens are pointing to it. What about doing the following: if an HERC contract is not able to pay its rent, then the tokens that point to the HERC contract should be liable to pay(i.e. the same account that pays for the token's rent should pay for the HERC contract rent). Since more than one token could point to the same HERC contract then the token with the largest auto-renew account balance should pay the HERC rent. And if this largest account does not have sufficient funds to pay for the rent, then take from the other tokens auto-renew accounts in descending order until sufficient rent is accumulated and if the total balance of all the tokens auto-renew accounts is still not sufficient then delete ALL tokens and the HERC contract.

So basically an HTS token can point to an HERC contract that it has no affiliation with, but in so doing assumes possible liability for rent in the case that the HERC contract isn't able to pay its rent.

---

That's what many-to-many would provide. One HERC enforces business hours, one may enforce a blocklist on transaction size limits. A token may put both HERCs on transfer to compose a "weekdays only, and no more than $100" rule. and other contracts may just use the $100 limit and others just the weekdays restriction.

Are you proposing a many-to-many or many-to-one relationship? I don't see any issue with a many-to-one relationship, but a many-to-many relationship would imo overcomplicate things(especially having to deal with rent for the list of HERCs that a token points to). Also, a many-to-many seems a bit redundant as a many-to-one relationship still allows developers to compose within a single HERC contract as that contract can still call other contracts to for example 'compose a "weekdays only, and no more than $100" rule'.

---