feat(deploy-sdk): deploy sdk core artifact api implementation

[xeno097]

Description

This PR adds the CoreWriter to the deploy-sdk for coordinating the deployment of core artifacts using the underlying protocol sdk writers.

• Adds the CoreWriter class to the deploy-sdk
• Adds the createMailboxArtifactManager and createValidatorAnnounceArtifactManager methods to the ProtocolProvider interface to get a mailbox and validator announce and updates the existing protocol providers to add placeholder methods where a core artifact implementation is not available yet

Drive-by changes

Related issues

Backward compatibility

• YES

Testing

---

Summary by CodeRabbit

• New Features

  • End-to-end core deployment workflow (mailbox, ISM, hooks, optional validator announce) via a new CoreWriter and factory; public exports added.
  • Protocol providers now surface mailbox and validator-announce artifact manager creation (implementations or placeholders across SDKs).

• Behavior

  • Core configs accept unset/zero-address placeholders; deploy/update flows handle address-driven and address-only paths.
  • Mailbox-scoped hook readers improve nested artifact expansion and consistency.

• Tests

  • Extensive unit tests covering CoreWriter and CoreArtifactReader create/update and error scenarios.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 76.49%. Comparing base (b9c6844) to head (8f172ef).
⚠️ Report is 17 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #8147   +/-   ##
=======================================
  Coverage   76.49%   76.49%           
=======================================
  Files         128      128           
  Lines        3416     3416           
  Branches      290      290           
=======================================
  Hits         2613     2613           
  Misses        786      786           
  Partials       17       17           

Flag	Coverage Δ
tron-sdk	68.83% <ø> (ø)

Flags with carried forward coverage won't be shown. Click here to find out more.

Components	Coverage Δ
core	87.80% <ø> (ø)
hooks	74.55% <ø> (ø)
isms	81.46% <ø> (ø)
token	87.33% <ø> (ø)
middlewares	85.47% <ø> (ø)

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[paulbalaji]

@claude review

[claude]

Claude finished @paulbalaji's task in 5m 47s —— View job

---

Review: deploy-sdk core artifact API

• Run code review analysis
• Post inline PR comments

Submitted a consolidated PR review with 5 inline comments covering:

Severity	Finding
Medium	hookWriter recreated per call in deployOrUpdateHook — should be created once in update()
Medium	Error propagation tests in describe('update') actually call coreWriter.create() — copy-paste from wrong block
Low	Discarded TxReceipt[] from sub-deployments during update()
Low	DerivedCoreConfig type widening with UnsetArtifactAddress — backwards-incompatible for existing consumers
Nit	fieldName: keyof DerivedCoreConfig overly coupled — string would suffice

Items already flagged by Devin (as any casts, validator announce throw vs null) were not repeated.

[coderabbitai]

📝 Walkthrough

Walkthrough

Adds a CoreWriter orchestrator and mailbox-scoped hook reader factory, introduces UnsetArtifactAddress and toDeployedOrUndefined helpers, extends ProtocolProvider with mailbox/validator artifact manager factories across SDKs, adjusts AltVMCoreModule for address-or-config handling, and adds comprehensive tests for reader/writer flows.

Changes

Cohort / File(s)	Summary
Provider artifact types & helpers typescript/provider-sdk/src/artifact.ts, typescript/provider-sdk/src/core.ts, typescript/provider-sdk/src/mailbox.ts	Add UnsetArtifactAddress and toDeployedOrUndefined; widen DerivedCoreConfig fields to accept unset addresses; change mailbox→derived conversion to handle UNDERIVED zero-address artifacts.
ProtocolProvider API & implementations typescript/provider-sdk/src/protocol.ts, typescript/*-sdk/src/clients/protocol.ts (Aleo, Cosmos, Radix, SVM, Tron)	Add factory methods createMailboxArtifactManager(...) and createValidatorAnnounceArtifactManager(...) to ProtocolProvider; implement or stub these across protocol providers (Aleo, Cosmos, Radix, SVM, Tron).
Core Writer / Reader typescript/deploy-sdk/src/core/core-writer.ts, typescript/deploy-sdk/src/core/core-artifact-reader.ts, typescript/deploy-sdk/src/index.ts	Introduce CoreWriter and createCoreWriter; implement create/update flows that orchestrate mailbox, ISM, hooks, and optional validator-announcement deployments; refactor CoreArtifactReader to use a mailbox-scoped hookReaderFactory.
AltVM core behavior typescript/deploy-sdk/src/AltVMCoreModule.ts	Allow ISM/hook parameters to be either config objects or address strings; use eqAddress/isEmptyAddress for robust comparisons; short-circuit address-only flows and normalize update annotations.
Hook writer tweak typescript/deploy-sdk/src/hook/hook-writer.ts	Treat empty (zero) addresses as absent hooks so a new hook is deployed when the stored address is zero.
Tests typescript/deploy-sdk/src/core/core-writer.test.ts, typescript/deploy-sdk/src/core/core-artifact-reader.test.ts	Add extensive unit tests for CoreWriter and CoreArtifactReader covering create/update flows, error propagation, zero-address handling, artifact expansion ordering, and receipt aggregation.
Exports & changesets typescript/deploy-sdk/src/index.ts, .changeset/*-core-artifact-api.md	Re-export CoreWriter/createCoreWriter; add changeset entries documenting CoreWriter/CoreArtifactReader and related artifact API changes.
Misc protocol SDK refactors typescript/radix-sdk/src/clients/protocol.ts, typescript/aleo-sdk/src/clients/protocol.ts, typescript/cosmos-sdk/src/clients/protocol.ts, typescript/svm-sdk/src/clients/protocol.ts, typescript/tron-sdk/src/clients/protocol.ts	Refactor network setup in Radix; add mailbox/validator artifact manager factory implementations or placeholders across protocol SDKs; wire domainId/rpc selection where applicable.

Sequence Diagram(s)

sequenceDiagram
    participant Client
    participant CoreWriter
    participant ProtocolProvider
    participant MailboxMgr as MailboxMgr
    participant ISMMgr as ISMMgr
    participant HookMgr as HookMgr
    participant VAMgr as ValidatorAnnounceMgr
    participant Signer
    participant Chain

    Client->>CoreWriter: create(mailbox artifact)
    CoreWriter->>ProtocolProvider: createMailboxArtifactManager(chainMetadata)
    CoreWriter->>ISMMgr: deploy ISM (if NEW)
    ISMMgr->>Chain: submit ISM tx
    Chain-->>ISMMgr: ISM address
    CoreWriter->>MailboxMgr: create mailbox (refs ISM/address)
    MailboxMgr->>Signer: sign creation
    Signer->>Chain: broadcast tx
    Chain-->>Signer: receipt
    par Deploy hooks (if NEW)
      CoreWriter->>HookMgr: deploy default hook (mailbox context)
      HookMgr->>Chain: submit hook tx
      HookMgr-->>CoreWriter: hook address
      CoreWriter->>HookMgr: deploy required hook (mailbox context)
    end
    CoreWriter->>MailboxMgr: update mailbox with hooks & ISM
    MailboxMgr->>Signer: sign update
    Signer->>Chain: broadcast update tx
    Chain-->>Signer: receipt
    opt Protocol supports VA
      CoreWriter->>VAMgr: deploy validator announce
      VAMgr->>Chain: submit VA tx
      Chain-->>VAMgr: VA address
    end
    CoreWriter-->>Client: return artifacts + receipts

Loading

sequenceDiagram
    participant Client
    participant CoreWriter
    participant CoreArtifactReader
    participant MailboxMgr as MailboxMgr
    participant ISMMgr as ISMMgr
    participant HookMgr as HookMgr
    participant Chain

    Client->>CoreWriter: update(expectedArtifact)
    CoreWriter->>CoreArtifactReader: deriveCoreConfig()
    CoreArtifactReader->>Chain: read mailbox state
    CoreArtifactReader->>ISMMgr: read ISM (skip if zero address)
    CoreArtifactReader->>HookMgr: read hooks (skip if zero address)
    CoreWriter->>ISMMgr: deployOrUpdateIsm (if changed)
    CoreWriter->>HookMgr: deployOrUpdateHook (if changed)
    CoreWriter->>MailboxMgr: update mailbox config
    MailboxMgr->>Chain: submit update tx
    Chain-->>MailboxMgr: receipt
    CoreWriter-->>Client: updated artifact + receipts

Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~45 minutes

Poem

In a muddy patch of code and rhyme,
CoreWriter stomps in, takes its time.
ISMs, hooks, and mailboxes align,
Deploys roll up like swampy vine—
All tidy now, one happy grime.

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 50.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
Title check	✅ Passed	The title clearly summarizes the main change: adding CoreWriter implementation with core artifact API support to deploy-sdk.
Description check	✅ Passed	The description covers the main implementation details and backward compatibility, but lacks specifics on testing methods and related issues.

_{✏️ 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 xeno/deploy-sdk-core-artifact-api

📝 Coding Plan

• Generate coding plan for human review comments

---

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.}

[devin-ai-integration]

Devin Review found 1 new potential issue.

View 6 additional findings in Devin Review.

[paulbalaji]

Review Summary

Clean PR that adds CoreWriter for orchestrating artifact-API-based core deployments (mailbox, ISM, hooks, validator announce). The 5-step create flow correctly handles the circular dependency between mailbox and hooks. The CoreArtifactReader composite pattern is well-structured. toDeployedOrUndefined and fromOnChainArtifact helpers follow the fail-fast assert() pattern.

Accounting for existing reviews (Claude, Devin, CodeRabbit) and the author's responses. Not re-flagging resolved items.

Key findings

#	Severity	Finding
1	Medium	update() has mixed execution model — deploys ISMs/hooks eagerly inside but returns AnnotatedTx[] — undocumented
2	Medium	DerivedCoreConfig widening diverges from SDK's DerivedCoreConfig — type-level inconsistency
3	Medium	Hook update/deploy path in update() has zero test coverage
4	Medium	Update tests don't verify address wiring or owner changes
5	Low	toDeployedOrUndefined and fromOnChainArtifact duplicate validation logic
6	Low	Reader tests bypass constructor via Object.create — hides constructor bugs

Notes on prior review findings

• Zero-address hook crash in AltVMCoreModule (raised by Claude/Devin): Confirmed stale — hook-writer.ts:171 now has !actualAddress || isEmptyAddress(actualAddress) guard.
• Receipt loss in deployOrUpdateIsm/Hook: Acknowledged by author as intentional per artifact API spec. The mixed execution model (finding #1) is the remaining documentation concern.
• SVM/Tron throw vs null for VA: Low severity — both createMailboxArtifactManager and createValidatorAnnounceArtifactManager throw, so createCoreWriter will fail at construction for these protocols regardless.

Observations Outside This PR

• typescript/sdk/src/core/types.ts: SDK's DerivedCoreConfig uses DerivedIsmConfig (no | string union), while provider-sdk's now allows | UnsetArtifactAddress. These are separate types but share the same name. Consumers importing from @hyperlane-xyz/sdk won't see the widening. CLI core read (via AltVMCoreReader) could emit ZERO_ADDRESS_HEX_32 strings. The SDK's CoreConfigSchema accepts strings via ZHash so parsing won't fail at runtime, but the type-level divergence is worth tracking.

[coderabbitai]

🧹 Nitpick comments (1)

typescript/deploy-sdk/src/core/core-writer.test.ts (1)

49-60: Trim unused protocol registry scaffolding in this test file.

TestProtocol registration + mockProtocolProvider setup looks unused here since tests construct CoreWriter directly. Dropping it would keep this test onion tighter and reduce global shared state.

♻️ Proposed cleanup

-// Test protocol
-const TestProtocol = 'test-core-writer' as ProtocolType;
-
-let mockProtocolProvider: ProtocolProvider;
-
-if (!hasProtocol(TestProtocol)) {
-  registerProtocol(TestProtocol, () => mockProtocolProvider);
-}
+// No protocol registration needed in this unit test file;
+// tests instantiate CoreWriter directly with artifact managers.

Also applies to: 143-157

🤖 Prompt for AI Agents

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

In `@typescript/deploy-sdk/src/core/core-writer.test.ts` around lines 49 - 60,
Remove the unused protocol registry scaffolding: delete the TestProtocol
constant, the mockProtocolProvider variable, and the conditional
hasProtocol/registerProtocol block (and the duplicate scaffolding around lines
143-157) since CoreWriter tests construct instances directly; also remove any
unused references to mockProtocolProvider and related protocol-registration
setup to avoid global test state and keep the file self-contained.

🤖 Prompt for all review comments with AI agents

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

Nitpick comments:
In `@typescript/deploy-sdk/src/core/core-writer.test.ts`:
- Around line 49-60: Remove the unused protocol registry scaffolding: delete the
TestProtocol constant, the mockProtocolProvider variable, and the conditional
hasProtocol/registerProtocol block (and the duplicate scaffolding around lines
143-157) since CoreWriter tests construct instances directly; also remove any
unused references to mockProtocolProvider and related protocol-registration
setup to avoid global test state and keep the file self-contained.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 68d0e9ab-8869-4983-8f46-7d48ab0a2a07

📥 Commits

Reviewing files that changed from the base of the PR and between b72f41f and 8f172ef.

📒 Files selected for processing (3)

• typescript/deploy-sdk/src/core/core-writer.test.ts
• typescript/deploy-sdk/src/core/core-writer.ts
• typescript/provider-sdk/src/mailbox.ts

🚧 Files skipped from review as they are similar to previous changes (1)

• typescript/deploy-sdk/src/core/core-writer.ts

[paulbalaji]

All findings addressed. LGTM.