feat: rebalance to hub pool script

[md0x]

Changes Proposed in this PR:

This PR introduces scripts to manage the full lifecycle of a rootBundle workflow for rebalancing USDC between the SVM Spoke Pool and the Hub Pool on mainnet. The process includes proposing a rootBundle, executing it after the liveness period, bridging via CCTP, and handling liabilities. The workflow is divided into three scripts:

• proposeRebalanceToHubPool: Proposes the rebalance from the Spoke Pool to the Hub Pool in the Hub Pool.
• executeRebalanceToHubPool: Executes the approved rebalance in the Hub Pool, bridges it via CCTP to the Spoke Pool, and processes the relayer refund leaf to create the liability.
• bridgeLiabilityToHubPool: Bridges any pending liability from the SVM Spoke Pool back to the Hub Pool via CCTP.

[Reinis-FRP]

better reuse TOKEN_SYMBOLS_MAP as exported in utils/constants.ts

[md0x]

Do you mean doing this?
c17299c

[Reinis-FRP]

kindof, but better avoid putting the var in constants and not pass chainId. E.g. can pull required token for required chain dynamically, like here

[md0x]

You are absolutely right. I fixed it here: 10a60f2

[Reinis-FRP]

why is pool rebalance needed, cannot it be zero hash?

[md0x]

I haven’t been able to do it with a zero hash in the poolRebalanceTree. I think we need to pass at least a tree with one leaf; the leaf can be constructed with zero hashes, except for the chain ID. Otherwise, we cannot get past this line when calling executeRootBundle:

contracts/contracts/HubPool.sol

Lines 635 to 651 in 1606063

	// Verify the props provided generate a leaf that, along with the proof, are included in the merkle root.
	require(
	MerkleLib.verifyPoolRebalance(
	rootBundleProposal.poolRebalanceRoot,
	PoolRebalanceLeaf({
	chainId: chainId,
	groupIndex: groupIndex,
	bundleLpFees: bundleLpFees,
	netSendAmounts: netSendAmounts,
	runningBalances: runningBalances,
	leafId: leafId,
	l1Tokens: l1Tokens
	}),
	proof
	),
	"Bad Proof"
	);

Additionally, the chain ID needs to be valid; otherwise, this line fails:

contracts/contracts/HubPool.sol

Line 655 in 1606063

(address adapter, address spokePool) = _getInitializedCrossChainContracts(chainId);

[Reinis-FRP]

oh, yes, you're totally right on this!

[chrismaree]

this script is SUPER useful. This will basically be what the finalizer needs to do in production.

[chrismaree]

only comment I could make on this script (but I think it's fine as we do similar things all over the place) is this assumes we are working with USDC.

[md0x]

Yeah, in many places we have dependencies on USDC, including in our smart contracts (solana adapter) and svm programs. Do you think it’s worth generalizing?

[chrismaree]

just an irritating nit that like with the other scripts we have 120 chars to work with so we don't need to wrap shorter than 120.

[md0x]

Fixed!

[chrismaree]

so this is provided to re-construct the merkle leaf & proof? it also assumes that there are no relayer repayments within the leaf, right?

in practice, I don't think this is how this flow will work, right? it's assumed that the data worker will post the leafs & proofs to a public location so these can be retrieved. this particular script flow is only useful in this particular situation where you don't have any relayer repayments & we only do a net repayment.

It would be useful to be able to pass in the leafs as en env/json or something like this? this would let you take them from the script that does the proposing, save them, and then not need to re-generate them. it would also better track with what things will look like when we interface with the data worker later (executor should not need to generate leafs, just get given them)

[chrismaree]

(prehaps this is still useful if we are dealing with JUST creating leafs to pull/push tokens to/from SVM via the netSendAmount

[md0x]

Yes, exactly. The netSendAmount is merely to avoid having to pass leaves, roots, proofs, etc., between this script and proposeRebalanceToHubPool.ts. It also assumes that the poolRebalanceTree has a single leaf with empty data and the solanaChainId. Thus, both scripts are dependent on each other. I believe they do not showcase a real production scenario; they are more like helpers to test the rebalance from the SVM Spoke to the HubPool.

On the other hand, I separated bridgeLiabilityToHubPool.ts from them because this one could represent a real use case, as you pointed out. It’s essentially what the finalizer needs to do.