feat: new layer of `FeePayer` as a helper for transaction final completion step #328

ashuralyk · 2025-11-03T11:20:22Z

Description

Add a new layer named FeePayer (could be changed further), to abstract our transaction complete step, like balancing process, paying with capacity margin or with DeFi swap ratio, etc.

This change can bring much clearer layer hierarchy on CCC, it makes transaction completion step programmable.

changeset-bot · 2025-11-03T11:20:26Z

🦋 Changeset detected

Latest commit: cca8107

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 18 packages

Name	Type
@ckb-ccc/core	Patch
@ckb-ccc/eip6963	Patch
@ckb-ccc/joy-id	Patch
@ckb-ccc/lumos-patches	Patch
@ckb-ccc/nip07	Patch
@ckb-ccc/okx	Patch
@ckb-ccc/rei	Patch
@ckb-ccc/shell	Patch
@ckb-ccc/spore	Patch
@ckb-ccc/ssri	Patch
@ckb-ccc/udt	Patch
@ckb-ccc/uni-sat	Patch
@ckb-ccc/utxo-global	Patch
@ckb-ccc/xverse	Patch
@ckb-ccc/ccc	Patch
ckb-ccc	Patch
@ckb-ccc/connector	Patch
@ckb-ccc/connector-react	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

netlify · 2025-11-03T11:20:28Z

✅ Deploy Preview for liveccc ready!

Name	Link
🔨 Latest commit	`cca8107`
🔍 Latest deploy log	https://app.netlify.com/projects/liveccc/deploys/69301e61f370c40008043597
😎 Deploy Preview	https://deploy-preview-328--liveccc.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.
Lighthouse	1 paths audited Performance: 23 (🟢 up 3 from production) Accessibility: 88 (no change from production) Best Practices: 92 (🔴 down 8 from production) SEO: 100 (no change from production) PWA: - View the detailed breakdown and full score reports

To edit notification comments on pull requests, go to your Netlify project configuration.

netlify · 2025-11-03T11:20:28Z

✅ Deploy Preview for apiccc ready!

Name	Link
🔨 Latest commit	`cca8107`
🔍 Latest deploy log	https://app.netlify.com/projects/apiccc/deploys/69301e6129a35b00084aa66e
😎 Deploy Preview	https://deploy-preview-328--apiccc.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.
Lighthouse	1 paths audited Performance: 88 (🟢 up 6 from production) Accessibility: 100 (no change from production) Best Practices: 100 (no change from production) SEO: 94 (no change from production) PWA: - View the detailed breakdown and full score reports

To edit notification comments on pull requests, go to your Netlify project configuration.

netlify · 2025-11-03T11:20:28Z

✅ Deploy Preview for appccc ready!

Name	Link
🔨 Latest commit	`cca8107`
🔍 Latest deploy log	https://app.netlify.com/projects/appccc/deploys/69301e6182f46b000891802a
😎 Deploy Preview	https://deploy-preview-328--appccc.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.
Lighthouse	1 paths audited Performance: 68 (🔴 down 7 from production) Accessibility: 89 (🟢 up 1 from production) Best Practices: 92 (🔴 down 8 from production) SEO: 100 (no change from production) PWA: - View the detailed breakdown and full score reports

To edit notification comments on pull requests, go to your Netlify project configuration.

netlify · 2025-11-03T11:22:56Z

✅ Deploy Preview for docsccc ready!

Name	Link
🔨 Latest commit	`cca8107`
🔍 Latest deploy log	https://app.netlify.com/projects/docsccc/deploys/69301e616f68bc00089bc82f
😎 Deploy Preview	https://deploy-preview-328--docsccc.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.
Lighthouse	1 paths audited Performance: 65 (🔴 down 2 from production) Accessibility: 88 (no change from production) Best Practices: 92 (no change from production) SEO: 92 (no change from production) PWA: - View the detailed breakdown and full score reports

To edit notification comments on pull requests, go to your Netlify project configuration.

ashuralyk · 2025-11-13T11:56:11Z

further implementation on margin fee payer for Spore module, here it is: ashuralyk#8

@Hanssen0

ashuralyk · 2025-11-19T14:11:08Z

/gemini review

gemini-code-assist

Code Review

This pull request introduces a new FeePayer abstraction layer to handle the transaction completion step, which is a significant and positive architectural change. It successfully decouples fee payment logic from the Transaction class, making it more modular and extensible. The refactoring of the Signer class to leverage this new abstraction is clean. However, I've identified a critical issue in the new completeByFeePayer method where the return value of prepareTransaction is ignored, potentially leading to incorrect transaction preparation and fee calculation.

packages/core/src/ckb/transaction.ts

…ases

Hanssen0 · 2025-11-21T03:48:34Z

packages/core/src/ckb/transaction.ts

+    ...feePayers: FeePayer[]
+  ): Promise<void> {
+    for (const feePayer of feePayers) {
+      await feePayer.prepareTransaction(this);


I agree with Gemini here: we should use the return value of prepareTransaction rather than assuming it modifies the tx in place. The previous implementation should be considered a bug.

Possible situation: A wallet (like JoyID, a web wallet) decides to handle the prepareTransaction stage itself to support more lock scripts in the future, and we serialize the tx for the API. This prevents the operation from happening in place.

To fix this problem without changing APIs, I assume we can use Transaction.copy to modify this at the end of completeBy* methods.

ashuralyk · 2025-12-10T13:34:37Z

/gemini review

gemini-code-assist

Code Review

This pull request introduces a new FeePayer abstraction layer, significantly improving the modularity and extensibility of transaction completion logic. By moving the fee calculation and input collection responsibilities from the Transaction class to dedicated FeePayer and FeePayerFromAddress classes, the codebase becomes cleaner and more maintainable. The Signer class now correctly extends FeePayerFromAddress, inheriting these capabilities. The new test cases for margin calculation and the FeePayer layer are comprehensive and well-structured, ensuring the new functionality works as expected. This is a well-executed architectural improvement.

gemini-code-assist · 2025-12-10T13:38:49Z

packages/core/src/ckb/transaction.test.ts

+
+      await tx.completeByFeePayer(client, mockFeePayer1, mockFeePayer2);
+
+      expect(mockFeePayer1.prepareTransaction).toHaveBeenCalledWith(tx);


The completeByFeePayer method clones the transaction before passing it to prepareTransaction. Therefore, mockFeePayer1.prepareTransaction receives a clone of the original tx, not the original tx object itself. The current assertion toHaveBeenCalledWith(tx) will likely fail because tx is the original transaction instance, not the cloned one passed to the mock. Consider asserting with expect.any(ccc.Transaction) or expect.objectContaining if specific properties of the cloned transaction need to be verified.

Suggested change

expect(mockFeePayer1.prepareTransaction).toHaveBeenCalledWith(tx);

expect(mockFeePayer1.prepareTransaction).toHaveBeenCalledWith(expect.any(ccc.Transaction));

gemini-code-assist · 2025-12-10T13:38:49Z

packages/core/src/ckb/transaction.test.ts

+      await tx.completeByFeePayer(client, mockFeePayer1, mockFeePayer2);
+
+      expect(mockFeePayer1.prepareTransaction).toHaveBeenCalledWith(tx);
+      expect(mockFeePayer2.prepareTransaction).toHaveBeenCalledWith(tx);


Similar to the previous comment, mockFeePayer2.prepareTransaction also receives a cloned transaction. The assertion toHaveBeenCalledWith(tx) should be updated to reflect this.

Suggested change

expect(mockFeePayer2.prepareTransaction).toHaveBeenCalledWith(tx);

expect(mockFeePayer2.prepareTransaction).toHaveBeenCalledWith(expect.any(ccc.Transaction));

Hanssen0

Great design for the FeePayer aspect! This should help us reduce future workload. However, this PR still needs to be polished to be developer-friendly.

An important note here is that TypeLike is usually for parameter types, while Type is for member/variable types. If a member of a new type has a TypeLike type, it almost always means the new type should also be a TypeLike.

I suggest making new option types here TypeLike, and adding corresponding new Type for them. For example:

export interface FeeRateOptionsLike {
  feeRate?: NumLike;
  options?: {
    feeRateBlockRange?: NumLike;
    maxFeeRate?: NumLike;
  };
}

export class FeeRateOptions {
  constructor(
    public readonly feeRate?: Num;
    public readonly options?: {
      feeRateBlockRange?: Num;
      maxFeeRate?: Num;
    }
  ) {}

  ...
}

Hanssen0 · 2026-01-07T07:22:26Z

packages/core/src/ckb/transaction.ts

    }, numFrom(0));
  }

+  getOutputCapacityMargin(index: number): Num {


It seems that both margin and getOutputCapacityMargin methods are not used in this PR. Let's remove them until we see the actual use case.

Hanssen0 · 2026-01-07T07:22:52Z

.changeset/tender-nails-stick.md

@@ -0,0 +1,6 @@
+---
+"@ckb-ccc/core": patch


This should be a minor change since it introduced new APIs.

Hanssen0 · 2026-01-07T07:25:55Z

packages/core/src/ckb/transaction.ts

-      addedCount: collectedCells.length,
-      accumulated: acc,
-    };
+    const { addedCount, accumulated } = await from.completeInputs(


I'm good with moving completeInputs to FeePayer interface to allow devs to customize input collection logic. But it seems that we're currently placing these methods in the FeePayerFromAddress class, which means other FeePayers like FeePayerGroup can't use this method.

To apply this change, I need to move getAddressObjs pairing with completeInputs as well, I originally thought the concept of Address is dedicated for FeePayerFromAddress only, not a general concept for all of FeePayers

Hanssen0 · 2026-01-07T07:28:49Z

packages/core/src/signer/feePayer/feePayer.ts

+export abstract class FeePayer {
+  constructor() {}
+
+  abstract completeTxFee(


Do you think it's better to make completeTxFee a pure function (tx: TxLike) => Tx? Modifying a function argument in place is always confusing and problem-causing.

Also, this helps us to relax the parameter type restriction from Tx to TxLike.

To avoid misunderstanding of your suggestion, are you only pointing out to replace the first parameter of tx: Transaction into tx: TransactionLike, despite erasing the others after it?

Hanssen0 · 2026-01-07T07:33:05Z

packages/core/src/signer/feePayer/feePayerFromAddress.ts

+    };
+  }
+
+  setOptionalProperties(props: {


Instead of setting/changing options after constructing an instance, I suggest we put these parameters in the class constructor.

Because of the original implementation, these options are set per related method as an optional function parameter, this causes each call of those methods can accept totally different options even they belong to a same instance.

Moving the initialization of those options into class constructor is absolutely fine, but do we still keep setOptionalProperties method for the opportunity of changing them for the next call of other methods?

Hanssen0 · 2026-01-07T07:34:35Z

packages/core/src/signer/feePayer/feePayerGroup.ts

+    return this;
+  }
+
+  pop(): FeePayer | undefined {


It's hard to see the use case where we need to modify the fee payers after creating the group. I think we should just remove the push & pop method and let devs specify them before constructing.

Hanssen0 · 2026-01-07T07:37:16Z

packages/core/src/signer/signer/index.ts

-export abstract class Signer {
-  constructor(protected client_: Client) {}
+export abstract class Signer extends FeePayerFromAddress {
+  constructor(protected client_: Client) {


I do think it should make our life easier if we move this client_ member to FeePayer, so that we can eliminate those client parameters appearing in every method.

So, your suggestion is about replacing extending Signer with FeePayerFromAddress with just injecting an abstracted parameter FeePayer to its constructor?

ashuralyk added 2 commits October 30, 2025 14:38

feat: fee payer initialization

239835a

feat: create a template for fee payer layer

7656820

ashuralyk added 2 commits November 4, 2025 21:48

chore: apply fee payer manager on transaction

69b5e50

chore: downgrade address related methods from Signer to SignerFeePayer

5d1b344

ashuralyk changed the title ~~feat: fee payer~~ feat: new layer of FeePayer as a helper for transaction final completion step Nov 5, 2025

ashuralyk added 4 commits November 12, 2025 21:57

feat: solve cocurrence issue and doing rename

ed5bfe8

chore: rename group file

e796fc1

chore: rewise spore test

efa1e9e

chore: adapt transaction test cases for new implementation

e36515a

ashuralyk marked this pull request as ready for review November 13, 2025 11:56

gemini-code-assist bot reviewed Nov 19, 2025

View reviewed changes

packages/core/src/ckb/transaction.ts Show resolved Hide resolved

chore: fix data length fixed point issue and prepare dedicated test c…

a524235

…ases

Hanssen0 requested changes Nov 21, 2025

View reviewed changes

ashuralyk added 2 commits December 3, 2025 13:03

chore: make use of the result of prepareTransaction

4c7b4cd

chore: return Transaction for mock prepareTransaction method

cca8107

gemini-code-assist bot reviewed Dec 10, 2025

View reviewed changes

Hanssen0 requested changes Jan 7, 2026

View reviewed changes

Hanssen0 mentioned this pull request Jan 12, 2026

feat(core): Add bytesLen and bytesLenUnsafe utilities #353

Merged


		await tx.completeByFeePayer(client, mockFeePayer1, mockFeePayer2);

		expect(mockFeePayer1.prepareTransaction).toHaveBeenCalledWith(tx);

	expect(mockFeePayer2.prepareTransaction).toHaveBeenCalledWith(tx);
	expect(mockFeePayer2.prepareTransaction).toHaveBeenCalledWith(expect.any(ccc.Transaction));

feat: new layer of FeePayer as a helper for transaction final completion step #328

Are you sure you want to change the base?

feat: new layer of FeePayer as a helper for transaction final completion step #328

Uh oh!

Conversation

ashuralyk commented Nov 3, 2025

Description

Uh oh!

changeset-bot bot commented Nov 3, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

netlify bot commented Nov 3, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for liveccc ready!

Uh oh!

netlify bot commented Nov 3, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for apiccc ready!

Uh oh!

netlify bot commented Nov 3, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for appccc ready!

Uh oh!

netlify bot commented Nov 3, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for docsccc ready!

Uh oh!

ashuralyk commented Nov 13, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

ashuralyk commented Nov 19, 2025

Uh oh!

gemini-code-assist bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ashuralyk commented Dec 10, 2025

Uh oh!

gemini-code-assist bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

gemini-code-assist bot Dec 10, 2025

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist bot Dec 10, 2025

Choose a reason for hiding this comment

Uh oh!

Hanssen0 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!

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!

Reviewers

Assignees

Labels

feat: new layer of `FeePayer` as a helper for transaction final completion step #328

feat: new layer of `FeePayer` as a helper for transaction final completion step #328

changeset-bot bot commented Nov 3, 2025 •

edited

Loading

netlify bot commented Nov 3, 2025 •

edited

Loading

netlify bot commented Nov 3, 2025 •

edited

Loading

netlify bot commented Nov 3, 2025 •

edited

Loading

netlify bot commented Nov 3, 2025 •

edited

Loading

ashuralyk commented Nov 13, 2025 •

edited

Loading