feat(satp): add support for NFTs #3965

Tomas-Silva2187 · 2025-08-06T19:14:31Z

feat(satp): add support for NFTs

Implements support for cross-chain transfers of NFTs with Ethereum and Besu Leafs.

CLOSES #3869
Pull Request Requirements

Rebased onto upstream/main branch and squashed into single commit to help maintainers review it more efficient and to avoid spaghetti git commit graphs that obfuscate which commit did exactly what change, when and, why.
Have git sign off at the end of commit message to avoid being marked red. You can add -s flag when using git commit command. You may refer to this link for more information.
Follow the Commit Linting specification. You may refer to this link for more information.

Character Limit

Pull Request Title and Commit Subject must not exceed 72 characters (including spaces and special characters).
Commit Message per line must not exceed 80 characters (including spaces and special characters).

A Must Read for Beginners
For rebasing and squashing, here's a must read guide for beginners.

LordKubaya · 2025-08-07T13:26:21Z

packages/cactus-plugin-satp-hermes/src/main/solidity/contracts/SATPWrapperContract.sol

+        TokenType tt = tokens[tokenId].tokenType;
+        if(tt == TokenType.NONSTANDARD_FUNGIBLE || tt == TokenType.ERC20) {
+            if(tokens[tokenId].amount > 0) {
+                revert TokenLocked(tokenId);
+            } 
+        }
+        else if(tt == TokenType.NONSTANDARD_NONFUNGIBLE || tt == TokenType.ERC721) {
+            if(tokens[tokenId].amount != 0) {
+                revert TokenLocked(tokenId);
+            }
+        }
+        else {
+            revert TokenTypeNotSupported(tokenId);


Shouldn't this be fungible and not fungible? Will the other standards have different APIs?

And for the contracts that are both fungible and not fungible?

TokensType were reduced, to keep track with the TokenTypes used by SATP. Also, the ERC standards were separated as another independent element that composes an asset

LordKubaya

Please take a look at the comments.

LordKubaya · 2025-08-07T13:27:11Z

packages/cactus-plugin-satp-hermes/src/main/solidity/contracts/SATPWrapperContract.sol

        if(lockSuccess) {
-            // The locked amount is added to the amount of the token struct
-            tokens[tokenId].amount += amount;
-            emit Lock(tokenId, amount);
+            TokenType tt = tokens[tokenId].tokenType;
+            if (tt == TokenType.ERC20 || tt == TokenType.NONSTANDARD_FUNGIBLE) {
+                // The locked amount is added to the amount of the token struct
+                tokens[tokenId].amount += assetAttribute;
+            }
+            else if (tt == TokenType.ERC721 || tt == TokenType.NONSTANDARD_NONFUNGIBLE) {
+                // When dealing with non-fungible tokens, the "amount" is interpreted as the token unique descriptor.
+                tokens[tokenId].amount = assetAttribute;
+            }
+            emit Lock(tokenId, assetAttribute);


If it is not of those types, what happens?

^ do error handling

LordKubaya · 2025-08-07T13:29:10Z

...s-plugin-satp-hermes/src/main/typescript/core/stage-services/client/stage0-client-service.ts

-
-          if (token.amount == undefined) {
-            throw new AmountMissingError(fnTag);
+          let token: FungibleAsset | NonFungibleAsset;


why don't you abstract this with a class name asset, and the fungible and non fungible are extensions of the same?

That would be probably the right thing to do, because in the future it will be easier to add new features. @Tomas-Silva2187, @LordKubaya, I propose a middle term, which is leaving this solution (provided it works), and @Tomas-Silva2187 creates a detailed issue with a proposal to implement what @LordKubaya proposed.

Done as @LordKubaya suggested

LordKubaya · 2025-08-07T13:30:59Z

packages/cactus-plugin-satp-hermes/src/main/typescript/core/stage-services/service-utils.ts

+      switch (asset.type) {
+        case TokenType.ERC20:
+        case TokenType.NONSTANDARD_FUNGIBLE:
+          protoAsset.amount = BigInt((asset as EvmFungibleAsset).amount);
+          protoAsset.contractAddress = (
+            asset as EvmFungibleAsset
+          ).contractAddress;
+          break;
+        case TokenType.ERC721:
+        case TokenType.NONSTANDARD_NONFUNGIBLE:
+          protoAsset.amount = BigInt(
+            (asset as EvmNonFungibleAsset).uniqueDescriptor,
+          );
+          protoAsset.contractAddress = (
+            asset as EvmNonFungibleAsset
+          ).contractAddress;
+          break;
+        default:
+          throw new Error(`Unsupported asset type ${asset.type}`);
+      }


I see these lines repeated multiple times. Maybe create a method to reduce redundancy?

LordKubaya · 2025-08-07T13:34:01Z

...us-plugin-satp-hermes/src/main/typescript/cross-chain-mechanisms/bridge/leafs/fabric-leaf.ts

            return this.wrapperContractName;
          case "NONFUNGIBLE":
-            //TODO implement
+            //TODO implement: can be the same wrapper of fungible assets


Why leave this comment? Isn't this PR the implementation of that?

This PR only implements NFT support for Ethereum and Besu. A new issue was created for Fabric support to be later implemented.

LordKubaya · 2025-08-07T13:34:35Z

...us-plugin-satp-hermes/src/main/typescript/cross-chain-mechanisms/bridge/leafs/fabric-leaf.ts

+          //Uncomment following snippet to allow non fungible tokens to be returned
+          /*return {
+              type: Number(token.tokenType),
+              id: token.tokenId,
+              referenceId: token.referenceId,
+              owner: token.owner,
+              mspId: token.mspId,
+              channelName: token.channelName,
+              contractName: token.contractName,
+              uniqueDescriptor: token.amount.toString(),
+              network: this.networkIdentification,
+            } as FabricNonFungibleAsset;*/


Why are these lines commented?

LordKubaya · 2025-08-07T13:41:31Z

packages/cactus-plugin-satp-hermes/src/test/solidity/tests/SATPNFTokenContractTest.sol

+    /*function testApprove() public {
+        uint256 tokenId = 1001;
+        vm.prank(bridge);
+        satpContract.mint(user, tokenId);
+        vm.startPrank(user);
+        satpContract.approveAsset(bridge, tokenId);
+        vm.stopPrank();
+
+        vm.prank(bridge);
+        bool allowance = satpContract.checkAssignment(bridge, tokenId);
+        assertEq(allowance, true, "Approval allowance mismatch");
+    }*/


why is this test commented

The test was corrected, and is now working

LordKubaya · 2025-08-07T13:42:08Z

packages/cactus-plugin-satp-hermes/src/test/solidity/tests/SATPWrapperTestFungible.sol

+    //function testMint() public {
+        //wrapperContract.wrap(contract1.name(), address(contract1), TokenType.NONSTANDARD_FUNGIBLE, contract1.name(), "refID", address(this), signatures);
+        //wrapperContract.mint(contract1.name(), 10);
+
+        //assertEq(contract1.balanceOf(address(this)), 10, "Token not minted");
+    //}


why is this test commented?

The test was corrected and is now working

LordKubaya · 2025-08-07T13:44:27Z

...ages/cactus-plugin-satp-hermes/src/test/typescript/environments/ethereum-test-environment.ts

          bytecode: contract.bytecode.object,
        },
-        keychainId: this.keychainPlugin1.getKeychainId(),
+        keychainId: this.keychainPluginFungible.getKeychainId(), // TODO: Should we use a different keyChainId for the oracle?


Why do you think we should?

This comment was due to a misunderstanding. Comment was cleared, and this keychain can still be used for both fungible contracts and oracle contracts

...gin-satp-hermes/src/test/typescript/integration/gateway/satp-e2e-transfer-2-gateways.test.ts

LordKubaya · 2025-08-07T13:49:55Z

...-plugin-satp-hermes/src/test/typescript/integration/oracle/oracle-execute-api-server.test.ts

+        },
+        [
+          {
+            assetType: SupportedBesuContractTypes.FUNGIBLE,


Why is this marked as an assetType fungible? Is this even an asset?
Can you fix this?

Fixed. ORACLE was defined as a SupportedContractType, to allow for a more logical support of this change to the test environments.

RafaelAPB · 2025-08-07T15:48:53Z

packages/cactus-plugin-satp-hermes/src/main/solidity/contracts/SATPWrapperContract.sol

 error InsuficientAmountLocked(string tokenId, uint256 amount);

+error TokenTypeNotSupported(string tokenId);
+


Possibly a better name is TokenNotSupported, because we only know what types we support.

Suggested change

error TokenNotSupported(string tokenId);

RafaelAPB · 2025-08-07T15:51:41Z

packages/cactus-plugin-satp-hermes/src/main/solidity/contracts/SATPWrapperContract.sol

-        if(tokens[tokenId].amount > 0) {
-            revert TokenLocked(tokenId);
+        TokenType tt = tokens[tokenId].tokenType;
+        if(tt == TokenType.NONSTANDARD_FUNGIBLE || tt == TokenType.ERC20) {


what do you mean by non standard fungible?

We support erc721 (non fungible) tokens and erc20 (fungible). we should probably refer to the specific standards that we support

Maybe in this situation, tokens that do not follow the ERC APIs

TokenTypes were reduced to Nonstandard Fungible and Nonstandard NonFungible. They kept this nomenclature due to an error in CBDC that occurs when these names are changed. As for the token standards, they were defined as new attribute of assets, independent of the TokenType.

RafaelAPB

Thank you very much for your contribution. Overall, this is an impressive contribution. Code is clean, tests are detailed and address the implemented functionality. Please do add documentation on your added feature - namely the "assetAttribute". It is understandable that this parameter is a generalization of the old "amount", but the different supported values should be well-documented.

Prior to merge, please address my and Carlo's comments - we can use the PR threads to discuss.

Great work!

RafaelAPB · 2025-08-07T15:52:13Z

packages/cactus-plugin-satp-hermes/src/main/solidity/contracts/SATPWrapperContract.sol

-        if(tokens[tokenId].amount > 0) {
-            revert TokenLocked(tokenId);
+        TokenType tt = tokens[tokenId].tokenType;
+        if(tt == TokenType.NONSTANDARD_FUNGIBLE || tt == TokenType.ERC20) {


We support erc721 (non fungible) tokens and erc20 (fungible). we should probably refer to the specific standards that we support

RafaelAPB · 2025-08-07T15:52:31Z

packages/cactus-plugin-satp-hermes/src/main/solidity/contracts/SATPWrapperContract.sol

        if(lockSuccess) {
-            // The locked amount is added to the amount of the token struct
-            tokens[tokenId].amount += amount;
-            emit Lock(tokenId, amount);
+            TokenType tt = tokens[tokenId].tokenType;
+            if (tt == TokenType.ERC20 || tt == TokenType.NONSTANDARD_FUNGIBLE) {
+                // The locked amount is added to the amount of the token struct
+                tokens[tokenId].amount += assetAttribute;
+            }
+            else if (tt == TokenType.ERC721 || tt == TokenType.NONSTANDARD_NONFUNGIBLE) {
+                // When dealing with non-fungible tokens, the "amount" is interpreted as the token unique descriptor.
+                tokens[tokenId].amount = assetAttribute;
+            }
+            emit Lock(tokenId, assetAttribute);


^ do error handling

RafaelAPB · 2025-08-07T15:53:59Z

packages/cactus-plugin-satp-hermes/src/main/solidity/contracts/SATPWrapperContract.sol

+        // upon minting, the minted attribute is set as the value that was minted 
+        // (may it be amount for fungibles, or uniqueDescriptor for non-fungibles)
+        tokens[tokenId].amount = assetAttribute;
+        emit Mint(tokenId, assetAttribute);


how does this asset attribute work, in particular? Please add documentation on what is the goal of this attribute and how we use it for different standards

RafaelAPB · 2025-08-07T15:54:43Z

packages/cactus-plugin-satp-hermes/src/main/solidity/contracts/SATPWrapperContract.sol

+     * @param assetAttribute The asset attribute of tokens to be encoded.
     */
-    function encodeParams(VarType[] memory variables, string memory tokenId, address receiver, uint256 amount)  internal view returns (bytes[] memory){
+    function encodeParams(VarType[] memory variables, string memory tokenId, address receiver, uint256 assetAttribute)  internal view returns (bytes[] memory){


this function should have a more specific name since it is not general-purpose encoding

Done. It was renamed as AssetParameterIdentifierEncoder, as it encodes custom parameters defined for the assets, to use them in contract calls.

RafaelAPB · 2025-08-07T16:05:49Z

...s-plugin-satp-hermes/src/main/typescript/core/stage-services/client/stage0-client-service.ts

-
-          if (token.amount == undefined) {
-            throw new AmountMissingError(fnTag);
+          let token: FungibleAsset | NonFungibleAsset;


That would be probably the right thing to do, because in the future it will be easier to add new features. @Tomas-Silva2187, @LordKubaya, I propose a middle term, which is leaving this solution (provided it works), and @Tomas-Silva2187 creates a detailed issue with a proposal to implement what @LordKubaya proposed.

RafaelAPB · 2025-08-07T16:11:10Z

...us-plugin-satp-hermes/src/main/typescript/cross-chain-mechanisms/bridge/leafs/fabric-leaf.ts

-          throw new WrapperContractError(
-            `${fnTag}, Wrapper Contract not deployed`,
-          );
+        switch (asset.type) {


same comments as in besu-leaf

This has been addressed

RafaelAPB · 2025-08-07T16:11:38Z

...lugin-satp-hermes/src/main/typescript/cross-chain-mechanisms/bridge/ontology/assets/asset.ts

  network: NetworkId;
 }

+export type Brand<K, T> = K & { __brand: T };


nice solution

RafaelAPB · 2025-08-07T16:12:37Z

...n-satp-hermes/src/main/typescript/cross-chain-mechanisms/bridge/ontology/assets/evm-asset.ts

 export interface EvmFungibleAsset extends EvmAsset, FungibleAsset {}
+export interface EvmNonFungibleAsset extends EvmAsset, NonFungibleAsset {}

 export enum VarType {


perhaps assetParameterIdentifier would be a more accurate name?

RafaelAPB · 2025-08-07T16:13:50Z

.../main/typescript/cross-chain-mechanisms/bridge/satp-bridge-execution-layer-implementation.ts


          const proof = await this.bridgeEndPoint.getProof(
            asset,
            this.claimType,


This looks great. However there is quite a lot of code duplication. Could you extract the functionality into a function that can be reused in these different related functionalities?

RafaelAPB · 2025-08-07T16:15:05Z

packages/cactus-plugin-satp-hermes/src/test/solidity/contracts/SATPNFTokenContract.sol

+/**
+ * @title SATPTokenContract
+ * The SATPTokenContract is an example of a custom ERC721 token contract.
+ * This is a simple contract, meaning it uses functions that assume everything is correct.


what do you mean that functions "assume everything is correct"?

Initially, the NFT contract was an unsafe OpenZeppelin version, which used functions that did not pre-check if the function caller had authorization over the asset it was interacting with. The currently implemented version uses safe functions, and the approve action, which is required to deal with these aspects of authorization, is implemented.

Signed-off-by: Tomás Silva <[email protected]>

RafaelAPB · 2025-09-29T16:22:12Z

@Tomas-Silva2187 most items seem to have been addressed. Could you please confirm that you addressed all comments (I see some items without a response). Thank you!

Tomas-Silva2187 requested a review from LordKubaya as a code owner August 6, 2025 19:14

Tomas-Silva2187 force-pushed the REDOnftSupportDev25-08-04 branch 2 times, most recently from 2ba814c to 52ac5ad Compare August 7, 2025 09:09

LordKubaya reviewed Aug 7, 2025

View reviewed changes

LordKubaya requested changes Aug 7, 2025

View reviewed changes

RafaelAPB self-assigned this Aug 7, 2025

RafaelAPB reviewed Aug 7, 2025

View reviewed changes

RafaelAPB requested changes Aug 7, 2025

View reviewed changes

RafaelAPB force-pushed the satp-stg branch from 3599d9e to a3e74ac Compare August 20, 2025 15:35

RafaelAPB requested review from takeutak, izuru0, VRamakrishna, sandeepnRES, outSH and AndreAugusto11 as code owners August 20, 2025 15:35

RafaelAPB force-pushed the satp-stg branch 2 times, most recently from 4cacbaf to 44f3bb4 Compare August 20, 2025 15:52

Tomas-Silva2187 force-pushed the REDOnftSupportDev25-08-04 branch from c548d20 to a03c7b0 Compare August 25, 2025 16:40

RafaelAPB force-pushed the satp-stg branch 7 times, most recently from 6617318 to 83f9482 Compare August 27, 2025 13:31

Tomas-Silva2187 force-pushed the REDOnftSupportDev25-08-04 branch from 1cb5caf to 392aa6e Compare August 28, 2025 22:09

RafaelAPB force-pushed the satp-stg branch from f86cc72 to 0333741 Compare August 29, 2025 19:40

Tomas-Silva2187 force-pushed the REDOnftSupportDev25-08-04 branch 2 times, most recently from f14db8d to 45e1e33 Compare August 31, 2025 17:02

RafaelAPB force-pushed the satp-stg branch 6 times, most recently from 88864ef to e7f952b Compare September 18, 2025 20:36

Tomas-Silva2187 force-pushed the REDOnftSupportDev25-08-04 branch from 59d6d7d to b830efc Compare September 20, 2025 21:21

RafaelAPB force-pushed the satp-stg branch 2 times, most recently from 724038e to bd7f382 Compare September 22, 2025 14:23

Tomas-Silva2187 force-pushed the REDOnftSupportDev25-08-04 branch from b830efc to 78bc4c6 Compare September 22, 2025 14:29

RafaelAPB force-pushed the satp-stg branch 15 times, most recently from b3bb285 to a14f896 Compare September 29, 2025 04:43

feat(satp): add support for NFTs

26c13ed

Signed-off-by: Tomás Silva <[email protected]>

Tomas-Silva2187 force-pushed the REDOnftSupportDev25-08-04 branch from 78bc4c6 to 26c13ed Compare September 29, 2025 10:44

RafaelAPB force-pushed the satp-stg branch 2 times, most recently from 9bee4bd to 1ae6a34 Compare October 1, 2025 13:03

		error InsuficientAmountLocked(string tokenId, uint256 amount);

		error TokenTypeNotSupported(string tokenId);

feat(satp): add support for NFTs #3965

Are you sure you want to change the base?

feat(satp): add support for NFTs #3965

Uh oh!

Conversation

Tomas-Silva2187 commented Aug 6, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

LordKubaya left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Tomas-Silva2187 Sep 11, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

RafaelAPB Aug 7, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

RafaelAPB left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Tomas-Silva2187 commented Aug 6, 2025 •

edited

Loading

Tomas-Silva2187 Sep 11, 2025 •

edited

Loading

RafaelAPB Aug 7, 2025 •

edited

Loading