sdk: add build transactions functions to route

[kev1n-peters]

Expose building transactions directly instead of having to capture them with a signer

Summary by CodeRabbit

• New Features

  • Added helpers to build unsigned transactions for initiate, complete, and finalize stages
  • Added a utility to collect transactions from async flows and expose unsigned transaction types
  • Initiate responses now include quote params

• Refactor

  • Shifted transfer flows to sender-driven construction and centralized transaction collection
  • Improved validation, state handling, and early-return behavior across complete/finalize flows

[coderabbitai]

📝 Walkthrough

Walkthrough

Introduces sender-based transaction builders and public helpers that produce arrays of unsigned transactions (buildInitiateTransactions, buildCompleteTransactions, buildFinalizeTransactions), refactors internal _build...Xfer signatures to accept sender addresses, and adds a collectTransactions utility and workflow helpers for completion/finalization.

Changes

Cohort / File(s)	Summary
Core executor & multi-token logic sdk/route/src/executor/executor.ts, sdk/route/src/executor/multiToken.ts	Added buildInitiateTransactions, buildCompleteTransactions, buildFinalizeTransactions. Refactored _buildInitiateXfer signature from signer-based to sender-based; adjusted initiate/complete/finalize flows to use sender-derived xfers and transaction collection. Exposed UnsignedTransaction in public surface and imported collectTransactions.
Transaction collection utility sdk/route/src/executor/utils.ts	New collectTransactions function that consumes an AsyncGenerator<UnsignedTransaction> and returns a Promise<UnsignedTransaction[]>.
Workflow helpers / types sdk/route/src/types.ts	Added buildCompleteXfer and buildFinalizeXfer helpers to construct completion and finalization transfers with attestation and queued-transfer checks; complete/finalize flows updated to use these helpers and return null on certain early-exit conditions.

Sequence Diagram(s)

sequenceDiagram
    participant Client
    participant Executor
    participant Builder
    participant TxCollector
    participant Signer

    Client->>Executor: buildInitiateTransactions(request, sender, recipient, quote)
    Executor->>Builder: _buildInitiateXfer(request, sender, to, quote)
    Builder->>Builder: construct unsigned transfer(s)
    Builder-->>Executor: AsyncGenerator<UnsignedTransaction>
    Executor->>TxCollector: collectTransactions(asyncGen)
    TxCollector->>TxCollector: accumulate UnsignedTransaction[]
    TxCollector-->>Executor: UnsignedTransaction[]
    Executor-->>Client: UnsignedTransaction[]

    Client->>Signer: sign & send selected transactions
    Signer-->>Client: signed txids / receipts

Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~45 minutes

Suggested reviewers

• nvsriram
• nik-suri

Poem

🐰 I hop through builders, sender-first,
Collecting txs before they burst.
Unsigned lines in neat arrays,
Hopped to sign in later days —
A little rabbit cheers this burst! 🥕

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'sdk: add build transactions functions to route' accurately summarizes the main change of exposing new buildInitiateTransactions, buildCompleteTransactions, and buildFinalizeTransactions methods to the SDK route, which aligns with the PR objective of adding functions to build transactions without requiring a signer.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

• 📝 Generate docstrings (stacked PR)
• 📝 Generate docstrings (commit on current branch)

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch add-build-txns

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 2

🤖 Fix all issues with AI agents

In `@sdk/route/src/types.ts`:
- Around line 605-620: buildFinalizeXfer directly destructures
receipt.attestation.attestation and assumes the receipt is a queued transfer;
add a guard that validates the receipt is in the expected queued state (e.g.,
reuse the same check used by finalize such as isDestinationQueued or at minimum
verify receipt.attestation and receipt.attestation.attestation exist and contain
the expected fields) and throw a clear, descriptive error if the precondition is
not met; ensure the error mentions buildFinalizeXfer and the missing/invalid
attestation so callers get actionable feedback (or alternatively document the
required precondition in the public API if you prefer not to throw).
- Around line 592-603: The complete function in types.ts calls buildCompleteXfer
and signSendWait but returns the original receipt, losing state and txid
updates; capture the result from signSendWait, update the receipt state to
DestinationInitiated and set receipt.destinationTxs (or the appropriate field)
from the transaction id(s) returned by signSendWait (mirroring executor.ts
complete behavior), then return the mutated receipt; if the omission was
intentional, add a brief comment in complete explaining that state/tx updates
are handled elsewhere (e.g., by the track generator).

🧹 Nitpick comments (2)

sdk/route/src/executor/multiToken.ts (1)

617-628: sender parameter is unused in buildCompleteTransactions.

The sender parameter is accepted but never forwarded to MultiTokenNttRoute.buildCompleteXfer, which only takes (chain, receipt). Same applies to buildFinalizeTransactions (line 650). This is presumably for API consistency with NttExecutorRoute.buildCompleteTransactions (which does use sender), but it may confuse callers into thinking the sender influences the built transactions.

Consider either documenting why sender is accepted but unused, or using an underscore prefix (_sender) to signal intent.

sdk/route/src/executor/executor.ts (1)

699-747: Redundant isDestinationQueued check in finalize.

_buildFinalizeXfer (line 700) already validates isDestinationQueued and throws. finalize (line 732) repeats the same check. Not a bug—just a minor redundancy. You could remove the outer check in finalize or keep it for fail-fast clarity before constructing sender.

[dvgui]

lgtm

[coderabbitai]

🧹 Nitpick comments (1)

sdk/route/src/executor/multiToken.ts (1)

617-628: Remove unused sender parameter or document why MultiTokenNtt doesn't require it.

The sender parameter in both buildCompleteTransactions (line 617) and buildFinalizeTransactions (line 650) is never used. Unlike the base NttExecutorRoute which forwards sender to _buildCompleteXfer and _buildFinalizeXfer, the MultiTokenNttRoute helper methods (buildCompleteXfer and buildFinalizeXfer) don't accept a sender parameter. If this is intentional due to MultiTokenNtt protocol differences, add a comment explaining why. Otherwise, remove the unused parameter.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@sdk/route/src/executor/multiToken.ts` around lines 617 - 628, The sender
parameter is unused in MultiTokenNttRoute.buildCompleteTransactions and
buildFinalizeTransactions; either remove the unused sender parameter from those
method signatures to match that
MultiTokenNttRoute.buildCompleteXfer/buildFinalizeXfer do not require it, or if
omission is intentional, add a short clarifying comment in each method
(referencing buildCompleteTransactions, buildFinalizeTransactions and the helper
methods MultiTokenNttRoute.buildCompleteXfer and
MultiTokenNttRoute.buildFinalizeXfer) explaining why MultiTokenNtt protocol does
not need the sender while the base NttExecutorRoute does.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Nitpick comments:
In `@sdk/route/src/executor/multiToken.ts`:
- Around line 617-628: The sender parameter is unused in
MultiTokenNttRoute.buildCompleteTransactions and buildFinalizeTransactions;
either remove the unused sender parameter from those method signatures to match
that MultiTokenNttRoute.buildCompleteXfer/buildFinalizeXfer do not require it,
or if omission is intentional, add a short clarifying comment in each method
(referencing buildCompleteTransactions, buildFinalizeTransactions and the helper
methods MultiTokenNttRoute.buildCompleteXfer and
MultiTokenNttRoute.buildFinalizeXfer) explaining why MultiTokenNtt protocol does
not need the sender while the base NttExecutorRoute does.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 3c1c097b-39a4-40cf-958f-645f85f399fe

📥 Commits

Reviewing files that changed from the base of the PR and between 67f5381 and 608a260.

📒 Files selected for processing (4)

• sdk/route/src/executor/executor.ts
• sdk/route/src/executor/multiToken.ts
• sdk/route/src/executor/utils.ts
• sdk/route/src/types.ts