feat(pool): improve SwapCallback conventions (#1009)

* feat(pool): improve SwapCallback conventions

* test: refactor swap callback parameter datatypes

* chore: update swap callback docs

* test: fix conventions

* fix: parameters

* test: fix callback parameters

* test: fix callback parameters

* test: fix callback parameters

* test: fix callback parameters

Author: jinoosss

contract/r/gnoswap/pool/README.md

@@ -62,6 +62,51 @@ Core swap execution (called by Router).
 - Calculates fees
 - Maintains TWAP oracle
 
+#### Swap Callback
+
+The `Swap` function uses a callback pattern for token transfers, following the Uniswap V3 flash swap design.
+
+**Callback Signature**:
+```go
+func(cur realm, amount0Delta, amount1Delta int64) error
+```
+
+**Delta Convention**:
+| Delta | Meaning |
+|-------|---------|
+| Positive (`> 0`) | Amount the pool must RECEIVE (input token) |
+| Negative (`< 0`) | Amount the pool has SENT (output token) |
+
+**Swap Direction Examples**:
+
+For `zeroForOne = true` (token0 → token1):
+- `amount0Delta > 0`: Pool receives token0 (input)
+- `amount1Delta < 0`: Pool sends token1 (output)
+
+For `zeroForOne = false` (token1 → token0):
+- `amount0Delta < 0`: Pool sends token0 (output)
+- `amount1Delta > 0`: Pool receives token1 (input)
+
+**Callback Implementation Example**:
+```go
+func swapCallback(cur realm, amount0Delta, amount1Delta int64) error {
+    if amount0Delta > 0 {
+        // Transfer token0 to pool
+        token0.Transfer(poolAddr, amount0Delta)
+    }
+    if amount1Delta > 0 {
+        // Transfer token1 to pool
+        token1.Transfer(poolAddr, amount1Delta)
+    }
+    return nil
+}
+```
+
+**Important Notes**:
+- The callback MUST transfer at least the positive delta amount to the pool
+- Return `nil` on success, or an error to revert the swap
+- Pool validates balance increase after callback execution
+
 ## Technical Details
 
 ### Price Math

contract/r/gnoswap/pool/_mock_test.gno

@@ -117,7 +117,7 @@ func (m *MockPool) Swap(
 	amountSpecified string,
 	sqrtPriceLimitX96 string,
 	payer address,
-	swapCallback func(cur realm, amount0Delta, amount1Delta string) error,
+	swapCallback func(cur realm, amount0Delta, amount1Delta int64) error,
 ) (string, string) {
 	res, ok := m.Response.Get("Swap")
 	if !ok {

contract/r/gnoswap/pool/proxy.gno

@@ -199,7 +199,7 @@ func Swap(
 	amountSpecified string,
 	sqrtPriceLimitX96 string,
 	payer address,
-	swapCallback func(cur realm, amount0Delta, amount1Delta string) error,
+	swapCallback func(cur realm, amount0Delta, amount1Delta int64) error,
 ) (string, string) {
 	return getImplementation().Swap(
 		token0Path,

contract/r/gnoswap/pool/types.gno

@@ -103,7 +103,7 @@ type IPoolSwap interface {
 		amountSpecified string,
 		sqrtPriceLimitX96 string,
 		payer address,
-		swapCallback func(cur realm, amount0Delta, amount1Delta string) error,
+		swapCallback func(cur realm, amount0Delta, amount1Delta int64) error,
 	) (string, string)
 
 	SetSwapEndHook(hook func(cur realm, poolPath string) error)

contract/r/gnoswap/pool/upgrade_test.gno

@@ -532,7 +532,7 @@ func TestSwap(t *testing.T) {
 		testing.SetRealm(tt.callerRealm)
 
 		// Action
-		Swap(cross, tt.token0Path, tt.token1Path, tt.fee, tt.recipient, tt.zeroForOne, tt.amountSpecified, tt.sqrtPriceLimitX96, tt.caller, func(cur realm, amount0Delta string, amount1Delta string) error {
+		Swap(cross, tt.token0Path, tt.token1Path, tt.fee, tt.recipient, tt.zeroForOne, tt.amountSpecified, tt.sqrtPriceLimitX96, tt.caller, func(cur realm, amount0Delta int64, amount1Delta int64) error {
 			return nil
 		})
 

contract/r/gnoswap/pool/v1/_helper_test.gno

@@ -3,7 +3,6 @@ package v1
 import (
 	"chain"
 	"chain/banker"
-	"strconv"
 	"testing"
 
 	"gno.land/r/gnoland/wugnot"
@@ -614,28 +613,25 @@ func TestBurnTokens(t *testing.T) {
 	uassert.Equal(t, bar.BalanceOf(addr01), int64(0)) // 100_000_000 -> 0
 }
 
-func mockSwapCallback(token0Path string, token1Path string, amount0Delta string, amount1Delta string) error {
+func mockSwapCallback(token0Path string, token1Path string, amount0Delta int64, amount1Delta int64) error {
 	func(cur realm) {
 		testing.SetRealm(adminRealm)
 
-		amount0Int64, _ := strconv.ParseInt(amount0Delta, 10, 64)
-		amount1Int64, _ := strconv.ParseInt(amount1Delta, 10, 64)
-
-		if amount0Int64 > 0 {
+		if amount0Delta > 0 {
 			if token0Path == wugnotPath {
-				testing.SetOriginSend(chain.Coins{{ugnotDenom, amount0Int64}})
+				testing.SetOriginSend(chain.Coins{{ugnotDenom, amount0Delta}})
 				wugnot.Deposit(cross)
 			}
 
-			common.SafeGRC20Transfer(cross, token0Path, poolAddr, amount0Int64)
+			common.SafeGRC20Transfer(cross, token0Path, poolAddr, amount0Delta)
 		}
-		if amount1Int64 > 0 {
+		if amount1Delta > 0 {
 			if token1Path == wugnotPath {
-				testing.SetOriginSend(chain.Coins{{ugnotDenom, amount1Int64}})
+				testing.SetOriginSend(chain.Coins{{ugnotDenom, amount1Delta}})
 				wugnot.Deposit(cross)
 			}
 
-			common.SafeGRC20Transfer(cross, token1Path, poolAddr, amount1Int64)
+			common.SafeGRC20Transfer(cross, token1Path, poolAddr, amount1Delta)
 		}
 	}(cross)
 
@@ -781,7 +777,7 @@ func mockInstanceCollectProtocol(token0Path string, token1Path string, fee uint3
 	}(cross)
 }
 
-func mockInstanceSwap(token0Path string, token1Path string, fee uint32, recipient address, zeroForOne bool, amountSpecified string, sqrtPriceLimitX96 string, payer address, swapCallback func(cur realm, amount0Delta string, amount1Delta string) error) (string, string) {
+func mockInstanceSwap(token0Path string, token1Path string, fee uint32, recipient address, zeroForOne bool, amountSpecified string, sqrtPriceLimitX96 string, payer address, swapCallback func(cur realm, amount0Delta int64, amount1Delta int64) error) (string, string) {
 	return func(cur realm) (string, string) {
 		const currentPoolPath = "gno.land/r/gnoswap/pool"
 		testing.SetRealm(testing.NewCodeRealm(currentPoolPath))

contract/r/gnoswap/pool/v1/dsl_test.gno

@@ -164,7 +164,7 @@ func (e *PoolTestEnv) WhenSwapExecuted(params SwapParams) (*u256.Uint, *u256.Uin
 		e.t.Fatalf("Pool not found for %s/%s/%d", params.token0, params.token1, params.fee)
 	}
 
-	swapCallback := func(cur realm, amount0Delta string, amount1Delta string) error {
+	swapCallback := func(cur realm, amount0Delta int64, amount1Delta int64) error {
 		testing.SetRealm(adminRealm)
 		if params.zeroForOne {
 			common.SafeGRC20Transfer(cross, params.token0, e.currentAddress, math.MaxInt64)

contract/r/gnoswap/pool/v1/pool_test.gno

@@ -944,7 +944,7 @@ func simulateSwapActivity(t *testing.T, pool *pl.Pool) {
 	approveTokenForRouter(t, pool.Token0Path())
 
 	mockInstanceSwap(pool.Token0Path(), pool.Token1Path(), pool.Fee(),
-		adminAddr, true, "1000000", "3945129629379410362911094631", adminAddr, func(cur realm, amount0Delta string, amount1Delta string) error {
+		adminAddr, true, "1000000", "3945129629379410362911094631", adminAddr, func(cur realm, amount0Delta int64, amount1Delta int64) error {
 			return mockSwapCallback(pool.Token0Path(), pool.Token1Path(), amount0Delta, amount1Delta)
 		})
 

contract/r/gnoswap/pool/v1/protocol_fee_test.gno

@@ -579,17 +579,14 @@ func TestProtocolFeesDisabledWhenNotConfigured(t *testing.T) {
 		adminAddr,
 	)
 
-	swapCallback := func(cur realm, amount0Delta string, amount1Delta string) error {
+	swapCallback := func(cur realm, amount0Delta int64, amount1Delta int64) error {
 		testing.SetRealm(adminRealm)
 
-		amount0Int64, _ := strconv.ParseInt(amount0Delta, 10, 64)
-		amount1Int64, _ := strconv.ParseInt(amount1Delta, 10, 64)
-
-		if amount0Int64 > 0 {
-			common.SafeGRC20Transfer(cross, barPath, poolAddr, amount0Int64)
+		if amount0Delta > 0 {
+			common.SafeGRC20Transfer(cross, barPath, poolAddr, amount0Delta)
 		}
-		if amount1Int64 > 0 {
-			common.SafeGRC20Transfer(cross, fooPath, poolAddr, amount1Int64)
+		if amount1Delta > 0 {
+			common.SafeGRC20Transfer(cross, fooPath, poolAddr, amount1Delta)
 		}
 
 		return nil

contract/r/gnoswap/pool/v1/swap.gno

@@ -132,7 +132,7 @@ func (i *poolV1) Swap(
 	amountSpecified string,
 	sqrtPriceLimitX96 string,
 	payer address,
-	swapCallback func(cur realm, amount0Delta, amount1Delta string) error,
+	swapCallback func(cur realm, amount0Delta, amount1Delta int64) error,
 ) (string, string) {
 	halt.AssertIsNotHaltedPool()
 
@@ -240,15 +240,15 @@ func (i *poolV1) Swap(
 		if result.Amount1.IsNeg() {
 			i.safeTransfer(pool, recipient, token1Path, result.Amount1.Abs(), false)
 
-			i.safeSwapCallback(pool, token0Path, result.Amount0.Abs(), zeroForOne, swapCallback)
+			i.safeSwapCallback(pool, token0Path, result.Amount0, result.Amount1, zeroForOne, swapCallback)
 		}
 	} else {
 		// receive token1 from swap callback
 		// send token0 to recipient (output)
 		if result.Amount0.IsNeg() {
 			i.safeTransfer(pool, recipient, token0Path, result.Amount0.Abs(), true)
 
-			i.safeSwapCallback(pool, token1Path, result.Amount1.Abs(), zeroForOne, swapCallback)
+			i.safeSwapCallback(pool, token1Path, result.Amount1, result.Amount0, zeroForOne, swapCallback)
 		}
 	}