Merge pull request #286 from pushchain/feat/pc20

feat: PC20 Feature

Author: 0xNilesh

api/uexecutor/v1/types.pulsar.go

@@ -117,6 +117,7 @@ message Inbound {
   RevertInstructions revert_instructions = 11; // revert config
   bool isCEA = 12; // isCEA is the boolean indicating this inbound is initiated by a CEA
   string raw_payload = 13; // hex-encoded raw payload bytes from source chain event; decoded into universal_payload by the core validator
+  bool is_pc20 = 14; // true when the raw payload carried the PC20 selector (a PC20 return: burn wrapper -> unlock locked native); set during NormalizeForTxType after the selector is stripped
 }
 
 message PCTx {
@@ -141,6 +142,7 @@ message OutboundObservation {
   string tx_hash = 3;           // external chain tx hash
   string error_msg = 4;
   string gas_fee_used = 5;      // actual gas fee consumed on destination chain; used to compute excess refund
+  string pc20_wrapper_address = 6; // PC20 only: wrapper address deployed on the destination chain (observed at settlement), used to flip the PC20 deploy flag
 }
 
 message OriginatingPcTx {
@@ -177,6 +179,8 @@ message OutboundTx {
   string refund_swap_error   = 19; // non-empty if swap-refund failed and we fell back to no-swap
   string gas_token           = 20; // gas token PRC20 address used to pay relayer fee
   string abort_reason        = 21; // Human-readable reason why the outbound was aborted
+  bool   is_pc20             = 22; // true when this outbound is a PC20 export (lock native on Push -> mint wrapper on dest); routes settlement/revert to the PC20 path
+  string pc20_contract_address = 23; // PC20 only: the Push-native PC20 token contract address (the locked source asset); used for VaultPC20.revertExport and the deploy-flag registry
 }
 
 message UniversalTx {

proto/uexecutor/v1/types.proto

@@ -0,0 +1,40 @@
+package integrationtest
+
+import (
+	"testing"
+
+	sdk "github.com/cosmos/cosmos-sdk/types"
+	"github.com/stretchr/testify/require"
+
+	utils "github.com/pushchain/push-chain-node/test/utils"
+	uexecutortypes "github.com/pushchain/push-chain-node/x/uexecutor/types"
+)
+
+// TestInboundRevertGasNotRefunded proves an INBOUND_REVERT never refunds gas on
+// settlement. A revert is protocol-initiated — the user was never charged a gas fee
+// for it — so even when a GasFee budget is present (PRC20 reverts set one) and the
+// observed gasFeeUsed is well below it, no refund must be attempted.
+func TestInboundRevertGasNotRefunded(t *testing.T) {
+	chainApp, ctx, vals, utxId, ob, coreVals := setupOutboundVotingTest(t, 4)
+
+	// Make the seeded outbound an INBOUND_REVERT carrying a gas budget with headroom
+	// that would otherwise trigger a refund (GasFee 1000, gasFeeUsed 100 below).
+	ob.TxType = uexecutortypes.TxType_INBOUND_REVERT
+	ob.GasFee = "1000"
+	ob.GasToken = "0x000000000000000000000000000000000000C0dE"
+	require.NoError(t, chainApp.UexecutorKeeper.UpdateOutbound(ctx, utxId, *ob))
+
+	// Settle it successfully with gasFeeUsed << GasFee.
+	for i := 0; i < 3; i++ {
+		valAddr, err := sdk.ValAddressFromBech32(coreVals[i].OperatorAddress)
+		require.NoError(t, err)
+		require.NoError(t, utils.ExecVoteOutbound(
+			t, ctx, chainApp, vals[i], sdk.AccAddress(valAddr).String(), utxId, ob, true, "", "100"))
+	}
+
+	utx, found, err := chainApp.UexecutorKeeper.GetUniversalTx(ctx, utxId)
+	require.NoError(t, err)
+	require.True(t, found)
+	require.Nil(t, utx.OutboundTx[0].PcRefundExecution,
+		"INBOUND_REVERT must not attempt a gas refund — the user was never charged for it")
+}

test/integration/uexecutor/gas_refund_test.go

@@ -0,0 +1,141 @@
+package integrationtest
+
+import (
+	"strings"
+	"testing"
+
+	sdk "github.com/cosmos/cosmos-sdk/types"
+	"github.com/ethereum/go-ethereum/common"
+	"github.com/mr-tron/base58"
+	"github.com/stretchr/testify/require"
+
+	utils "github.com/pushchain/push-chain-node/test/utils"
+	uexecutortypes "github.com/pushchain/push-chain-node/x/uexecutor/types"
+)
+
+// TestIsUeModuleAddress verifies the module-address check compares raw 20-byte
+// values (VM-native identity), so hex casing / EIP-55 checksum never matters and
+// a re-parsed lower/upper-case form of the module address still resolves as the
+// module — while any other address does not.
+func TestIsUeModuleAddress(t *testing.T) {
+	chainApp, ctx, _ := utils.SetAppWithValidators(t)
+	k := chainApp.UexecutorKeeper
+
+	moduleAddr, moduleHex := k.GetUeModuleAddress(ctx)
+
+	require.True(t, k.IsUeModuleAddress(ctx, moduleAddr), "the module address must resolve as the module")
+	// Re-parsed from all-lowercase hex → identical 20 bytes → still the module.
+	require.True(t, k.IsUeModuleAddress(ctx, common.HexToAddress(strings.ToLower(moduleHex))))
+	// Re-parsed from all-uppercase (non-checksummed) hex → identical 20 bytes → still the module.
+	require.True(t, k.IsUeModuleAddress(ctx, common.HexToAddress("0x"+strings.ToUpper(strings.TrimPrefix(moduleHex, "0x")))))
+
+	require.False(t, k.IsUeModuleAddress(ctx, common.HexToAddress("0x00000000000000000000000000000000dEadBeef")), "a different address is not the module")
+	require.False(t, k.IsUeModuleAddress(ctx, common.HexToAddress("0x1234567890AbCdeF1234567890abCDeF12345678")), "an unrelated EVM address is not the module")
+	require.False(t, k.IsUeModuleAddress(ctx, common.Address{}), "the zero address is not the module")
+
+	// A Solana (SVM) address folded into 20 bytes must not collide with the module.
+	solBytes, err := base58.Decode("So11111111111111111111111111111111111111112")
+	require.NoError(t, err)
+	require.False(t, k.IsUeModuleAddress(ctx, common.BytesToAddress(solBytes)), "an SVM-derived address is not the module")
+}
+
+// TestModuleNonce_NonModuleSenderDoesNotAdvanceModuleNonce proves the module-nonce
+// counter is only touched for a module sender. A non-module `from` skips the
+// module-nonce path entirely (before any EVM work), so ModuleAccountNonce is
+// unchanged regardless of whether the downstream EVM call itself succeeds.
+func TestModuleNonce_NonModuleSenderDoesNotAdvanceModuleNonce(t *testing.T) {
+	chainApp, ctx, _ := utils.SetAppWithValidators(t)
+	k := chainApp.UexecutorKeeper
+
+	before, err := k.GetModuleAccountNonce(ctx)
+	require.NoError(t, err)
+
+	user := common.HexToAddress("0x00000000000000000000000000000000000000A1")
+	uea := common.HexToAddress("0x00000000000000000000000000000000000000A2")
+	payload := &uexecutortypes.UniversalPayload{
+		To: user.Hex(), Value: "0", Data: "0x", GasLimit: "100000",
+		MaxFeePerGas: "0", MaxPriorityFeePerGas: "0", Nonce: "0", Deadline: "0",
+	}
+	// The EVM call may fail (no real UEA / no signature) — irrelevant to nonce
+	// accounting, which is decided before the call.
+	_, _ = k.CallUEAExecutePayload(ctx, user, uea, payload, nil)
+
+	after, err := k.GetModuleAccountNonce(ctx)
+	require.NoError(t, err)
+	require.Equal(t, before, after, "a non-module sender must not advance ModuleAccountNonce")
+}
+
+// TestModuleNonce_ModuleSenderAdvancesModuleNonce is the isolated regression: a
+// UEA payload execution sent by the module must advance ModuleAccountNonce by one.
+// Before the fix this call sourced its nonce from the (static) account sequence and
+// left ModuleAccountNonce untouched, so it silently reused whatever nonce a prior
+// module call in the same inbound had already used.
+func TestModuleNonce_ModuleSenderAdvancesModuleNonce(t *testing.T) {
+	app, ctx, _, _, _, ueaAddr := setupInboundInitiatedOutboundTest(t, 4)
+	k := app.UexecutorKeeper
+	moduleAddr, _ := k.GetUeModuleAddress(ctx)
+
+	before, err := k.GetModuleAccountNonce(ctx)
+	require.NoError(t, err)
+
+	// A minimal, freshly-nonced payload (UEA nonce is 0 right after deployment). The
+	// module sender bypasses the UEA signature check, so this executes; either way
+	// the module-nonce path runs before the EVM call.
+	payload := &uexecutortypes.UniversalPayload{
+		To: "0x00000000000000000000000000000000000000A9", Value: "0", Data: "0x",
+		GasLimit: "200000", MaxFeePerGas: "0", MaxPriorityFeePerGas: "0", Nonce: "0", Deadline: "0",
+	}
+	_, _ = k.CallUEAExecutePayload(ctx, moduleAddr, ueaAddr, payload, nil)
+
+	after, err := k.GetModuleAccountNonce(ctx)
+	require.NoError(t, err)
+	require.Equal(t, before+1, after, "a module-sender UEA execution must advance ModuleAccountNonce by exactly 1")
+}
+
+// TestModuleNonce_InboundPayloadExecutionAdvancesModuleNonce is the end-to-end
+// regression. A FUNDS_AND_PAYLOAD inbound makes two module-sender EVM calls — the
+// funds deposit AND the UEA payload execution — and each must advance
+// ModuleAccountNonce (Δ2). Before the fix the payload execution didn't, so Δ was 1
+// and the UEA tx reused the deposit's nonce.
+func TestModuleNonce_InboundPayloadExecutionAdvancesModuleNonce(t *testing.T) {
+	app, ctx, vals, inbound, coreVals, _ := setupInboundInitiatedOutboundTest(t, 4)
+	k := app.UexecutorKeeper
+
+	before, err := k.GetModuleAccountNonce(ctx)
+	require.NoError(t, err)
+
+	for i := 0; i < 3; i++ {
+		valAddr, err := sdk.ValAddressFromBech32(coreVals[i].OperatorAddress)
+		require.NoError(t, err)
+		require.NoError(t, utils.ExecVoteInbound(t, ctx, app, vals[i], sdk.AccAddress(valAddr).String(), inbound))
+	}
+
+	after, err := k.GetModuleAccountNonce(ctx)
+	require.NoError(t, err)
+	require.Equal(t, uint64(2), after-before,
+		"deposit + UEA payload execution must each advance ModuleAccountNonce (Δ2); pre-fix Δ was 1")
+}
+
+// TestModuleNonce_ModuleDeployUEAAdvancesModuleNonce covers the CallFactoryToDeployUEA
+// path: the inbound flow deploys a UEA for a first-time user as the module, so that
+// deployment must also advance ModuleAccountNonce. Before the fix it ran the module
+// as a non-module sender and left the counter untouched (reusing a nonce).
+func TestModuleNonce_ModuleDeployUEAAdvancesModuleNonce(t *testing.T) {
+	app, ctx, _, _, _, _ := setupInboundInitiatedOutboundTest(t, 4)
+	k := app.UexecutorKeeper
+	moduleAddr, _ := k.GetUeModuleAddress(ctx)
+
+	before, err := k.GetModuleAccountNonce(ctx)
+	require.NoError(t, err)
+
+	// Deploy a UEA for a fresh owner AS THE MODULE (as the inbound path does).
+	freshUA := &uexecutortypes.UniversalAccountId{
+		ChainNamespace: "eip155", ChainId: "11155111",
+		Owner: "0x00000000000000000000000000000000000000Ab",
+	}
+	_, _ = k.DeployUEAV2(ctx, moduleAddr, freshUA)
+
+	after, err := k.GetModuleAccountNonce(ctx)
+	require.NoError(t, err)
+	require.Equal(t, before+1, after, "a module-sender UEA deployment must advance ModuleAccountNonce by 1")
+}

test/integration/uexecutor/module_nonce_test.go

@@ -0,0 +1,164 @@
+package integrationtest
+
+import (
+	"encoding/hex"
+	"math/big"
+	"strings"
+	"testing"
+
+	sdk "github.com/cosmos/cosmos-sdk/types"
+	stakingtypes "github.com/cosmos/cosmos-sdk/x/staking/types"
+	"github.com/ethereum/go-ethereum/accounts/abi"
+	"github.com/ethereum/go-ethereum/common"
+	"github.com/stretchr/testify/require"
+
+	"github.com/pushchain/push-chain-node/app"
+	utils "github.com/pushchain/push-chain-node/test/utils"
+	uexecutortypes "github.com/pushchain/push-chain-node/x/uexecutor/types"
+)
+
+// pc20InboundWrapper is an external PC20 wrapper address that Push never mapped —
+// so getPC20Source (on the un-wired UniversalCore) can't resolve a source for it.
+var pc20InboundWrapper = common.HexToAddress("0x000000000000000000000000000000000000face")
+
+// encodePC20UserPayload ABI-encodes a minimal (but decodable) UniversalPayload,
+// the "user payload" that rides behind the PC20 selector on a return.
+func encodePC20UserPayload(t *testing.T, to common.Address) string {
+	t.Helper()
+	tupleType, err := abi.NewType("tuple", "", []abi.ArgumentMarshaling{
+		{Name: "to", Type: "address"},
+		{Name: "value", Type: "uint256"},
+		{Name: "data", Type: "bytes"},
+		{Name: "gasLimit", Type: "uint256"},
+		{Name: "maxFeePerGas", Type: "uint256"},
+		{Name: "maxPriorityFeePerGas", Type: "uint256"},
+		{Name: "nonce", Type: "uint256"},
+		{Name: "deadline", Type: "uint256"},
+		{Name: "vType", Type: "uint8"},
+	})
+	require.NoError(t, err)
+
+	type up struct {
+		To                   common.Address
+		Value                *big.Int
+		Data                 []byte
+		GasLimit             *big.Int
+		MaxFeePerGas         *big.Int
+		MaxPriorityFeePerGas *big.Int
+		Nonce                *big.Int
+		Deadline             *big.Int
+		VType                uint8
+	}
+	packed, err := abi.Arguments{{Type: tupleType}}.Pack(up{
+		To:                   to,
+		Value:                big.NewInt(0),
+		Data:                 []byte{},
+		GasLimit:             big.NewInt(21000),
+		MaxFeePerGas:         big.NewInt(1000000000),
+		MaxPriorityFeePerGas: big.NewInt(200000000),
+		Nonce:                big.NewInt(0),
+		Deadline:             big.NewInt(9999999999),
+		VType:                1,
+	})
+	require.NoError(t, err)
+	return "0x" + hex.EncodeToString(packed)
+}
+
+// pc20SelectorPrefixed returns a raw inbound payload with the PC20 selector in
+// front of a decodable user payload — the shape the external gateway emits.
+func pc20SelectorPrefixed(t *testing.T) string {
+	return "0x" + uexecutortypes.PC20Selector + strings.TrimPrefix(
+		encodePC20UserPayload(t, common.HexToAddress("0x000000000000000000000000000000000000beef")), "0x")
+}
+
+func votePC20InboundToQuorum(t *testing.T, ctx sdk.Context, chainApp *app.ChainApp, vals []string, coreVals []stakingtypes.Validator, inbound *uexecutortypes.Inbound) {
+	t.Helper()
+	for i := 0; i < 3; i++ {
+		valAddr, err := sdk.ValAddressFromBech32(coreVals[i].OperatorAddress)
+		require.NoError(t, err)
+		require.NoError(t, utils.ExecVoteInbound(t, ctx, chainApp, vals[i], sdk.AccAddress(valAddr).String(), inbound))
+	}
+}
+
+func hasInboundRevert(utx uexecutortypes.UniversalTx) *uexecutortypes.OutboundTx {
+	for _, ob := range utx.OutboundTx {
+		if ob.TxType == uexecutortypes.TxType_INBOUND_REVERT {
+			return ob
+		}
+	}
+	return nil
+}
+
+// TestPC20Inbound_Routing drives PC20 returns (external chain -> Push) end to end
+// through the vote/finalize/execute path. The PC20-aware UniversalCore
+// (getPC20Source) and VaultPC20 (unlock) are not wired into this harness, so the
+// funds step can't complete — but the routing decision (is_pc20 detection + strip,
+// unlock vs deposit, revert vs no-revert) is fully observable. The happy round-trip
+// (unlock releases funds, stripped payload executes) is gated on those contract
+// bytecodes and covered separately once they're deployed.
+func TestPC20Inbound_Routing(t *testing.T) {
+	t.Run("non-CEA PC20 return routes to unlock and reverts when source is unresolvable", func(t *testing.T) {
+		chainApp, ctx, vals, inbound, coreVals, _ := setupInboundInitiatedOutboundTest(t, 4)
+
+		inbound.AssetAddr = pc20InboundWrapper.Hex()
+		inbound.IsCEA = false
+		inbound.UniversalPayload = nil
+		inbound.RawPayload = pc20SelectorPrefixed(t)
+
+		votePC20InboundToQuorum(t, ctx, chainApp, vals, coreVals, inbound)
+
+		utx, found, err := chainApp.UexecutorKeeper.GetUniversalTx(ctx, uexecutortypes.GetInboundUniversalTxKey(*inbound))
+		require.NoError(t, err)
+		require.True(t, found)
+
+		require.True(t, utx.InboundTx.IsPc20, "PC20 selector must be detected and flagged")
+
+		rev := hasInboundRevert(utx)
+		require.NotNil(t, rev, "an unresolvable PC20 return must produce an INBOUND_REVERT (wrapper re-mint)")
+		// The revert re-mints the wrapper: carries the wrapper as external asset and
+		// must NOT be flagged is_pc20 (a failed INBOUND_REVERT must never route into
+		// handleFailedOutbound's revertExport, which is only for a failed export).
+		require.Equal(t, pc20InboundWrapper.Hex(), rev.ExternalAssetAddr)
+		require.False(t, rev.IsPc20)
+	})
+
+	t.Run("CEA PC20 return that can't resolve source does NOT revert", func(t *testing.T) {
+		chainApp, ctx, vals, inbound, coreVals, ueaAddr := setupInboundInitiatedOutboundTest(t, 4)
+
+		// CEA inbound: recipient is explicit (a deployed UEA). CEA failures never
+		// create an INBOUND_REVERT — the PC20 unlock failure must honour that.
+		inbound.AssetAddr = pc20InboundWrapper.Hex()
+		inbound.IsCEA = true
+		inbound.Recipient = ueaAddr.Hex()
+		inbound.UniversalPayload = nil
+		inbound.RawPayload = pc20SelectorPrefixed(t)
+
+		votePC20InboundToQuorum(t, ctx, chainApp, vals, coreVals, inbound)
+
+		utx, found, err := chainApp.UexecutorKeeper.GetUniversalTx(ctx, uexecutortypes.GetInboundUniversalTxKey(*inbound))
+		require.NoError(t, err)
+		require.True(t, found)
+
+		require.True(t, utx.InboundTx.IsPc20, "PC20 selector must be detected even on a CEA return")
+		require.Nil(t, hasInboundRevert(utx), "a CEA PC20 return must NOT create an INBOUND_REVERT")
+	})
+
+	t.Run("un-prefixed (PRC20) inbound is not flagged pc20 and does not revert", func(t *testing.T) {
+		chainApp, ctx, vals, inbound, coreVals, _ := setupInboundInitiatedOutboundTest(t, 4)
+
+		// A raw payload with no PC20 selector: the tolerant router leaves it alone,
+		// is_pc20 stays false, and the funds step takes the PRC20 deposit path
+		// (registered token from setup) — diverging from the PC20 return above.
+		inbound.UniversalPayload = nil
+		inbound.RawPayload = encodePC20UserPayload(t, common.HexToAddress("0x000000000000000000000000000000000000beef"))
+
+		votePC20InboundToQuorum(t, ctx, chainApp, vals, coreVals, inbound)
+
+		utx, found, err := chainApp.UexecutorKeeper.GetUniversalTx(ctx, uexecutortypes.GetInboundUniversalTxKey(*inbound))
+		require.NoError(t, err)
+		require.True(t, found)
+
+		require.False(t, utx.InboundTx.IsPc20, "an un-prefixed payload must not be flagged pc20")
+		require.Nil(t, hasInboundRevert(utx), "PRC20 deposit path should complete without an INBOUND_REVERT")
+	})
+}