@recoillink/deploy-sdk 0.0.0-stage → 11.0.1

package/dist/core/core-writer.test.js

@@ -0,0 +1,1315 @@
+import { expect } from 'chai';
+import sinon from 'sinon';
+import { MockSigner, ProtocolType, hasProtocol, registerProtocol, } from '@recoillink/provider-sdk';
+import { ArtifactState, } from '@recoillink/provider-sdk/artifact';
+import { CompositeIsmNodeType, IsmType, } from '@recoillink/provider-sdk/ism';
+import { ZERO_ADDRESS_HEX_32 } from '@recoillink/utils';
+import { CoreWriter } from './core-writer.js';
+// Test protocol
+const TestProtocol = 'test-core-writer';
+let mockIsmArtifactManager;
+let mockHookArtifactManager;
+let mockProtocolProvider;
+if (!hasProtocol(TestProtocol)) {
+    registerProtocol(TestProtocol, () => mockProtocolProvider);
+}
+if (!hasProtocol(ProtocolType.Starknet)) {
+    registerProtocol(ProtocolType.Starknet, () => mockProtocolProvider);
+}
+describe('CoreWriter', () => {
+    const mockMailboxAddress = '0xMAILBOX';
+    const mockIsmAddress = '0xISM';
+    const mockNewIsmAddress = '0xNEWISM';
+    const mockDefaultHookAddress = '0xDEFAULTHOOK';
+    const mockRequiredHookAddress = '0xREQUIREDHOOK';
+    const mockValidatorAnnounceAddress = '0xVA';
+    const mockOwner = '0xOWNER';
+    const mockSignerAddress = '0xSIGNER';
+    const mockDomainId = 1;
+    const chainName = 'test-chain';
+    let createMailboxWriterStub;
+    let createVAWriterStub;
+    let getSignerAddressStub;
+    let sendAndConfirmTxStub;
+    let mailboxArtifactManager;
+    let validatorAnnounceArtifactManager;
+    let signer;
+    let chainLookup;
+    let chainMetadata;
+    let coreWriter;
+    const mockReceipt = {
+        transactionHash: '0xHASH',
+        blockNumber: 123,
+    };
+    const mockIsm = {
+        artifactState: ArtifactState.DEPLOYED,
+        config: {
+            type: IsmType.MERKLE_ROOT_MULTISIG,
+            validators: ['0xVALIDATOR1'],
+            threshold: 1,
+        },
+        deployed: { address: mockIsmAddress },
+    };
+    const mockDefaultHook = {
+        artifactState: ArtifactState.DEPLOYED,
+        config: {
+            type: 'merkleTreeHook',
+        },
+        deployed: { address: mockDefaultHookAddress },
+    };
+    const mockRequiredHook = {
+        artifactState: ArtifactState.DEPLOYED,
+        config: {
+            type: 'interchainGasPaymaster',
+            owner: mockOwner,
+            beneficiary: '0xBENEFICIARY',
+            oracleKey: '0xORACLE',
+            overhead: {},
+            oracleConfig: {},
+        },
+        deployed: { address: mockRequiredHookAddress },
+    };
+    beforeEach(async () => {
+        mockIsmArtifactManager = {
+            readIsm: sinon.stub(),
+            createReader: sinon.stub().returns({ read: sinon.stub() }),
+            createWriter: sinon.stub().returns({
+                create: sinon.stub(),
+                update: sinon.stub(),
+                read: sinon.stub(),
+            }),
+        };
+        mockHookArtifactManager = {
+            readHook: sinon.stub(),
+            createReader: sinon.stub().returns({ read: sinon.stub() }),
+            createWriter: sinon.stub().returns({
+                create: sinon.stub(),
+                update: sinon.stub(),
+                read: sinon.stub(),
+            }),
+        };
+        mockProtocolProvider = {
+            createProvider: sinon.stub(),
+            createSigner: sinon.stub(),
+            createSubmitter: sinon.stub(),
+            createIsmArtifactManager: sinon.stub(),
+            createHookArtifactManager: sinon.stub().returns(mockHookArtifactManager),
+            createMailboxArtifactManager: sinon.stub(),
+            createValidatorAnnounceArtifactManager: sinon.stub(),
+            createFeeArtifactManager: sinon.stub(),
+            getMinGas: sinon.stub(),
+            createWarpArtifactManager: sinon.stub(),
+        };
+        mockProtocolProvider.createIsmArtifactManager = sinon
+            .stub()
+            .returns(mockIsmArtifactManager);
+        signer = await MockSigner.connectWithSigner();
+        getSignerAddressStub = sinon.stub().returns(mockSignerAddress);
+        sinon.stub(signer, 'getSignerAddress').callsFake(getSignerAddressStub);
+        sendAndConfirmTxStub = sinon
+            .stub()
+            .resolves(mockReceipt);
+        sinon
+            .stub(signer, 'sendAndConfirmTransaction')
+            .callsFake(sendAndConfirmTxStub);
+        const mailboxCreateStub = sinon
+            .stub()
+            .resolves([
+            {
+                artifactState: ArtifactState.DEPLOYED,
+                config: {
+                    owner: mockSignerAddress,
+                    defaultIsm: {
+                        artifactState: ArtifactState.DEPLOYED,
+                        config: mockIsm.config,
+                        deployed: mockIsm.deployed,
+                    },
+                    defaultHook: {
+                        artifactState: ArtifactState.UNDERIVED,
+                        deployed: { address: ZERO_ADDRESS_HEX_32 },
+                    },
+                    requiredHook: {
+                        artifactState: ArtifactState.UNDERIVED,
+                        deployed: { address: ZERO_ADDRESS_HEX_32 },
+                    },
+                },
+                deployed: { address: mockMailboxAddress, domainId: mockDomainId },
+            },
+            [mockReceipt],
+        ]);
+        const mailboxUpdateStub = sinon
+            .stub()
+            .resolves([]);
+        const mockMailboxWriter = {
+            create: mailboxCreateStub,
+            update: mailboxUpdateStub,
+            read: sinon.stub(),
+        };
+        createMailboxWriterStub = sinon.stub().returns(mockMailboxWriter);
+        mailboxArtifactManager = {
+            readMailbox: sinon.stub(),
+            createReader: sinon.stub(),
+            createWriter: createMailboxWriterStub,
+        };
+        const vaCreateStub = sinon
+            .stub()
+            .resolves([
+            {
+                artifactState: ArtifactState.DEPLOYED,
+                config: { mailboxAddress: mockMailboxAddress },
+                deployed: { address: mockValidatorAnnounceAddress },
+            },
+            [mockReceipt],
+        ]);
+        const mockVAWriter = {
+            create: vaCreateStub,
+            update: sinon.stub(),
+            read: sinon.stub(),
+        };
+        createVAWriterStub = sinon.stub().returns(mockVAWriter);
+        validatorAnnounceArtifactManager = {
+            readValidatorAnnounce: sinon.stub(),
+            createReader: sinon.stub(),
+            createWriter: createVAWriterStub,
+        };
+        chainMetadata = {
+            name: chainName,
+            domainId: mockDomainId,
+            protocol: TestProtocol,
+            chainId: mockDomainId,
+        };
+        chainLookup = {
+            getChainMetadata: sinon
+                .stub()
+                .returns(chainMetadata),
+            getChainName: sinon.stub().returns(chainName),
+            getDomainId: sinon
+                .stub()
+                .returns(mockDomainId),
+            getKnownChainNames: sinon.stub().returns([chainName]),
+            getKnownDomainIds: sinon
+                .stub()
+                .returns(new Set([mockDomainId])),
+        };
+        coreWriter = new CoreWriter(mailboxArtifactManager, validatorAnnounceArtifactManager, chainMetadata, chainLookup, signer);
+    });
+    afterEach(() => {
+        sinon.restore();
+    });
+    describe('create', () => {
+        it('should deploy mailbox with NEW ISM and NEW hooks', async () => {
+            // ARRANGE
+            const artifact = {
+                artifactState: ArtifactState.NEW,
+                config: {
+                    owner: mockOwner,
+                    defaultIsm: {
+                        artifactState: ArtifactState.NEW,
+                        config: mockIsm.config,
+                    },
+                    defaultHook: {
+                        artifactState: ArtifactState.NEW,
+                        config: mockDefaultHook.config,
+                    },
+                    requiredHook: {
+                        artifactState: ArtifactState.NEW,
+                        config: mockRequiredHook.config,
+                    },
+                },
+            };
+            const ismCreateStub = sinon
+                .stub()
+                .callsFake(async () => [mockIsm, [mockReceipt]]);
+            const mockIsmWriter = {
+                create: ismCreateStub,
+                update: sinon.stub(),
+                read: sinon.stub(),
+            };
+            Object.defineProperty(coreWriter, 'ismWriter', {
+                value: mockIsmWriter,
+                writable: true,
+            });
+            const hookCreateStub = sinon
+                .stub()
+                .onFirstCall()
+                .callsFake(async () => [mockDefaultHook, [mockReceipt]])
+                .onSecondCall()
+                .callsFake(async () => [mockRequiredHook, [mockReceipt]]);
+            const mockHookWriter = {
+                create: hookCreateStub,
+                update: sinon.stub(),
+                read: sinon.stub(),
+            };
+            mockHookArtifactManager.createWriter = sinon
+                .stub()
+                .returns(mockHookWriter);
+            // ACT
+            const [result, receipts] = await coreWriter.create(artifact);
+            // ASSERT
+            expect(result.mailbox.deployed.address).to.equal(mockMailboxAddress);
+            expect(result.mailbox.config.owner).to.equal(mockOwner);
+            expect(result.validatorAnnounce).to.not.be.null;
+            expect(result.validatorAnnounce?.deployed.address).to.equal(mockValidatorAnnounceAddress);
+            expect(receipts.length).to.be.greaterThan(0);
+            sinon.assert.calledOnce(ismCreateStub);
+            sinon.assert.calledTwice(hookCreateStub);
+            sinon.assert.calledWith(createMailboxWriterStub, 'mailbox', signer);
+            sinon.assert.calledWith(createVAWriterStub, 'validatorAnnounce', signer);
+        });
+        it('should not forward config contractVersion into the create-path mailbox update', async () => {
+            // ARRANGE
+            const artifact = {
+                artifactState: ArtifactState.NEW,
+                config: {
+                    owner: mockOwner,
+                    defaultIsm: mockIsm,
+                    defaultHook: mockDefaultHook,
+                    requiredHook: mockRequiredHook,
+                    contractVersion: '1.0.0',
+                },
+            };
+            // ACT
+            const [result] = await coreWriter.create(artifact);
+            // ASSERT
+            expect(result.mailbox.config.contractVersion).to.be.undefined;
+        });
+        it('should use existing ISM when DEPLOYED', async () => {
+            // ARRANGE
+            const artifact = {
+                artifactState: ArtifactState.NEW,
+                config: {
+                    owner: mockOwner,
+                    defaultIsm: mockIsm,
+                    defaultHook: mockDefaultHook,
+                    requiredHook: mockRequiredHook,
+                },
+            };
+            const ismCreateStub = sinon.stub();
+            const mockIsmWriter = {
+                create: ismCreateStub,
+                update: sinon.stub(),
+                read: sinon.stub(),
+            };
+            Object.defineProperty(coreWriter, 'ismWriter', {
+                value: mockIsmWriter,
+                writable: true,
+            });
+            // ACT
+            await coreWriter.create(artifact);
+            // ASSERT
+            sinon.assert.notCalled(ismCreateStub);
+        });
+        it('should handle protocol without validator announce support', async () => {
+            // ARRANGE
+            const coreWriterNoVA = new CoreWriter(mailboxArtifactManager, null, chainMetadata, chainLookup, signer);
+            const artifact = {
+                artifactState: ArtifactState.NEW,
+                config: {
+                    owner: mockOwner,
+                    defaultIsm: mockIsm,
+                    defaultHook: mockDefaultHook,
+                    requiredHook: mockRequiredHook,
+                },
+            };
+            const mockIsmWriter = {
+                create: sinon.stub(),
+                update: sinon.stub(),
+                read: sinon.stub(),
+            };
+            Object.defineProperty(coreWriterNoVA, 'ismWriter', {
+                value: mockIsmWriter,
+                writable: true,
+            });
+            // ACT
+            const [result] = await coreWriterNoVA.create(artifact);
+            // ASSERT
+            expect(result.validatorAnnounce).to.be.null;
+        });
+        it('should create mailbox with signer as initial owner', async () => {
+            // ARRANGE
+            const artifact = {
+                artifactState: ArtifactState.NEW,
+                config: {
+                    owner: mockOwner,
+                    defaultIsm: mockIsm,
+                    defaultHook: mockDefaultHook,
+                    requiredHook: mockRequiredHook,
+                },
+            };
+            const mockIsmWriter = {
+                create: sinon.stub(),
+                update: sinon.stub(),
+                read: sinon.stub(),
+            };
+            Object.defineProperty(coreWriter, 'ismWriter', {
+                value: mockIsmWriter,
+                writable: true,
+            });
+            // ACT
+            await coreWriter.create(artifact);
+            // ASSERT
+            const mailboxWriter = createMailboxWriterStub.returnValues[0];
+            const mailboxCreateStub = mailboxWriter.create;
+            const initialConfig = mailboxCreateStub.firstCall.args[0].config;
+            expect(initialConfig.owner).to.equal(mockSignerAddress);
+            expect(initialConfig.owner).to.not.equal(mockOwner);
+        });
+        it('should create mailbox with zero-address hooks initially', async () => {
+            // ARRANGE
+            const artifact = {
+                artifactState: ArtifactState.NEW,
+                config: {
+                    owner: mockOwner,
+                    defaultIsm: mockIsm,
+                    defaultHook: {
+                        artifactState: ArtifactState.NEW,
+                        config: mockDefaultHook.config,
+                    },
+                    requiredHook: {
+                        artifactState: ArtifactState.NEW,
+                        config: mockRequiredHook.config,
+                    },
+                },
+            };
+            const mockIsmWriter = {
+                create: sinon.stub(),
+                update: sinon.stub(),
+                read: sinon.stub(),
+            };
+            Object.defineProperty(coreWriter, 'ismWriter', {
+                value: mockIsmWriter,
+                writable: true,
+            });
+            const mockHookWriter = {
+                create: sinon
+                    .stub()
+                    .onFirstCall()
+                    .callsFake(async () => [mockDefaultHook, [mockReceipt]])
+                    .onSecondCall()
+                    .callsFake(async () => [mockRequiredHook, [mockReceipt]]),
+                update: sinon.stub(),
+                read: sinon.stub(),
+            };
+            mockHookArtifactManager.createWriter = sinon
+                .stub()
+                .returns(mockHookWriter);
+            // ACT
+            await coreWriter.create(artifact);
+            // ASSERT
+            const mailboxWriter = createMailboxWriterStub.returnValues[0];
+            const mailboxCreateStub = mailboxWriter.create;
+            const initialConfig = mailboxCreateStub.firstCall.args[0].config;
+            expect(initialConfig.defaultHook.deployed.address).to.equal(ZERO_ADDRESS_HEX_32);
+            expect(initialConfig.requiredHook.deployed.address).to.equal(ZERO_ADDRESS_HEX_32);
+            expect(initialConfig.defaultHook.artifactState).to.equal(ArtifactState.UNDERIVED);
+        });
+        it('should keep zero-address hook placeholders for non-Starknet even when hooks are already on-chain', async () => {
+            const artifact = {
+                artifactState: ArtifactState.NEW,
+                config: {
+                    owner: mockOwner,
+                    defaultIsm: mockIsm,
+                    defaultHook: mockDefaultHook,
+                    requiredHook: mockRequiredHook,
+                },
+            };
+            const mockIsmWriter = {
+                create: sinon.stub(),
+                update: sinon.stub(),
+                read: sinon.stub(),
+            };
+            Object.defineProperty(coreWriter, 'ismWriter', {
+                value: mockIsmWriter,
+                writable: true,
+            });
+            await coreWriter.create(artifact);
+            const mailboxWriter = createMailboxWriterStub.returnValues[0];
+            const initialConfig = mailboxWriter.create.firstCall.args[0].config;
+            expect(initialConfig.defaultHook.deployed.address).to.equal(ZERO_ADDRESS_HEX_32);
+            expect(initialConfig.requiredHook.deployed.address).to.equal(ZERO_ADDRESS_HEX_32);
+        });
+        it('should defer Starknet noop hook bootstrap to the mailbox writer', async () => {
+            chainMetadata = {
+                ...chainMetadata,
+                protocol: ProtocolType.Starknet,
+            };
+            coreWriter = new CoreWriter(mailboxArtifactManager, validatorAnnounceArtifactManager, chainMetadata, chainLookup, signer);
+            const artifact = {
+                artifactState: ArtifactState.NEW,
+                config: {
+                    owner: mockOwner,
+                    defaultIsm: mockIsm,
+                    defaultHook: {
+                        artifactState: ArtifactState.NEW,
+                        config: mockDefaultHook.config,
+                    },
+                    requiredHook: {
+                        artifactState: ArtifactState.NEW,
+                        config: mockRequiredHook.config,
+                    },
+                },
+            };
+            const mockIsmWriter = {
+                create: sinon.stub(),
+                update: sinon.stub(),
+                read: sinon.stub(),
+            };
+            Object.defineProperty(coreWriter, 'ismWriter', {
+                value: mockIsmWriter,
+                writable: true,
+            });
+            const mockHookWriter = {
+                create: sinon
+                    .stub()
+                    .onFirstCall()
+                    .callsFake(async () => [mockDefaultHook, [mockReceipt]])
+                    .onSecondCall()
+                    .callsFake(async () => [mockRequiredHook, [mockReceipt]]),
+                update: sinon.stub(),
+                read: sinon.stub(),
+            };
+            mockHookArtifactManager.createWriter = sinon
+                .stub()
+                .returns(mockHookWriter);
+            await coreWriter.create(artifact);
+            const mailboxWriter = createMailboxWriterStub.returnValues[0];
+            const initialConfig = mailboxWriter.create.firstCall.args[0].config;
+            expect(initialConfig.defaultHook.deployed.address).to.equal(ZERO_ADDRESS_HEX_32);
+            expect(initialConfig.requiredHook.deployed.address).to.equal(ZERO_ADDRESS_HEX_32);
+            sinon.assert.notCalled(sendAndConfirmTxStub);
+        });
+        it('should pass through existing hook addresses during Starknet mailbox bootstrap', async () => {
+            chainMetadata = {
+                ...chainMetadata,
+                protocol: ProtocolType.Starknet,
+            };
+            coreWriter = new CoreWriter(mailboxArtifactManager, validatorAnnounceArtifactManager, chainMetadata, chainLookup, signer);
+            const artifact = {
+                artifactState: ArtifactState.NEW,
+                config: {
+                    owner: mockOwner,
+                    defaultIsm: mockIsm,
+                    defaultHook: mockDefaultHook,
+                    requiredHook: mockRequiredHook,
+                },
+            };
+            const mockIsmWriter = {
+                create: sinon.stub(),
+                update: sinon.stub(),
+                read: sinon.stub(),
+            };
+            Object.defineProperty(coreWriter, 'ismWriter', {
+                value: mockIsmWriter,
+                writable: true,
+            });
+            await coreWriter.create(artifact);
+            const mailboxWriter = createMailboxWriterStub.returnValues[0];
+            const initialConfig = mailboxWriter.create.firstCall.args[0].config;
+            expect(initialConfig.defaultHook.deployed.address).to.equal(mockDefaultHookAddress);
+            expect(initialConfig.requiredHook.deployed.address).to.equal(mockRequiredHookAddress);
+        });
+        it('should update mailbox with hooks and owner after deployment', async () => {
+            // ARRANGE
+            const artifact = {
+                artifactState: ArtifactState.NEW,
+                config: {
+                    owner: mockOwner,
+                    defaultIsm: mockIsm,
+                    defaultHook: mockDefaultHook,
+                    requiredHook: mockRequiredHook,
+                },
+            };
+            const mockIsmWriter = {
+                create: sinon.stub(),
+                update: sinon.stub(),
+                read: sinon.stub(),
+            };
+            Object.defineProperty(coreWriter, 'ismWriter', {
+                value: mockIsmWriter,
+                writable: true,
+            });
+            // ACT
+            await coreWriter.create(artifact);
+            // ASSERT
+            const mailboxWriter = createMailboxWriterStub.returnValues[0];
+            const mailboxUpdateStub = mailboxWriter.update;
+            sinon.assert.calledOnce(mailboxUpdateStub);
+            const updatedArtifact = mailboxUpdateStub.firstCall.args[0];
+            expect(updatedArtifact.config.owner).to.equal(mockOwner);
+            expect(updatedArtifact.config.defaultHook.deployed.address).to.equal(mockDefaultHookAddress);
+            expect(updatedArtifact.config.requiredHook.deployed.address).to.equal(mockRequiredHookAddress);
+        });
+        it('should execute update transactions via signer', async () => {
+            // ARRANGE
+            const mockUpdateTx = {
+                to: mockMailboxAddress,
+                data: '0xUPDATE',
+                annotation: 'Update hooks',
+            };
+            const mailboxCreateStub = sinon.stub().resolves([
+                {
+                    artifactState: ArtifactState.DEPLOYED,
+                    config: {
+                        owner: mockSignerAddress,
+                        defaultIsm: {
+                            artifactState: ArtifactState.DEPLOYED,
+                            config: mockIsm.config,
+                            deployed: mockIsm.deployed,
+                        },
+                        defaultHook: {
+                            artifactState: ArtifactState.UNDERIVED,
+                            deployed: { address: ZERO_ADDRESS_HEX_32 },
+                        },
+                        requiredHook: {
+                            artifactState: ArtifactState.UNDERIVED,
+                            deployed: { address: ZERO_ADDRESS_HEX_32 },
+                        },
+                    },
+                    deployed: { address: mockMailboxAddress, domainId: mockDomainId },
+                },
+                [mockReceipt],
+            ]);
+            const mailboxUpdateStub = sinon.stub().resolves([mockUpdateTx]);
+            const mockMailboxWriter = {
+                create: mailboxCreateStub,
+                update: mailboxUpdateStub,
+                read: sinon.stub(),
+            };
+            mailboxArtifactManager.createWriter = sinon
+                .stub()
+                .returns(mockMailboxWriter);
+            const artifact = {
+                artifactState: ArtifactState.NEW,
+                config: {
+                    owner: mockOwner,
+                    defaultIsm: mockIsm,
+                    defaultHook: mockDefaultHook,
+                    requiredHook: mockRequiredHook,
+                },
+            };
+            const mockIsmWriter = {
+                create: sinon.stub(),
+                update: sinon.stub(),
+                read: sinon.stub(),
+            };
+            Object.defineProperty(coreWriter, 'ismWriter', {
+                value: mockIsmWriter,
+                writable: true,
+            });
+            // ACT
+            await coreWriter.create(artifact);
+            // ASSERT
+            sinon.assert.calledWith(sendAndConfirmTxStub, mockUpdateTx);
+        });
+        it('should collect receipts from all steps', async () => {
+            // ARRANGE
+            const artifact = {
+                artifactState: ArtifactState.NEW,
+                config: {
+                    owner: mockOwner,
+                    defaultIsm: {
+                        artifactState: ArtifactState.NEW,
+                        config: mockIsm.config,
+                    },
+                    defaultHook: mockDefaultHook,
+                    requiredHook: mockRequiredHook,
+                },
+            };
+            const mockIsmWriter = {
+                create: sinon
+                    .stub()
+                    .callsFake(async () => [mockIsm, [mockReceipt, mockReceipt]]),
+                update: sinon.stub(),
+                read: sinon.stub(),
+            };
+            Object.defineProperty(coreWriter, 'ismWriter', {
+                value: mockIsmWriter,
+                writable: true,
+            });
+            // ACT
+            const [, receipts] = await coreWriter.create(artifact);
+            // ASSERT
+            expect(receipts.length).to.be.greaterThan(0);
+            expect(receipts.length).to.be.at.least(4);
+        });
+        it('should propagate ISM deployment errors', async () => {
+            // ARRANGE
+            const error = new Error('ISM deployment failed');
+            const artifact = {
+                artifactState: ArtifactState.NEW,
+                config: {
+                    owner: mockOwner,
+                    defaultIsm: {
+                        artifactState: ArtifactState.NEW,
+                        config: mockIsm.config,
+                    },
+                    defaultHook: mockDefaultHook,
+                    requiredHook: mockRequiredHook,
+                },
+            };
+            const mockIsmWriter = {
+                create: sinon.stub().rejects(error),
+                update: sinon.stub(),
+                read: sinon.stub(),
+            };
+            Object.defineProperty(coreWriter, 'ismWriter', {
+                value: mockIsmWriter,
+                writable: true,
+            });
+            // ACT & ASSERT
+            await expect(coreWriter.create(artifact)).to.be.rejectedWith('ISM deployment failed');
+        });
+        it('should propagate mailbox creation errors', async () => {
+            // ARRANGE
+            const error = new Error('Mailbox creation failed');
+            const mockMailboxWriter = {
+                create: sinon.stub().rejects(error),
+                update: sinon.stub(),
+                read: sinon.stub(),
+            };
+            mailboxArtifactManager.createWriter = sinon
+                .stub()
+                .returns(mockMailboxWriter);
+            const artifact = {
+                artifactState: ArtifactState.NEW,
+                config: {
+                    owner: mockOwner,
+                    defaultIsm: mockIsm,
+                    defaultHook: mockDefaultHook,
+                    requiredHook: mockRequiredHook,
+                },
+            };
+            const mockIsmWriter = {
+                create: sinon.stub(),
+                update: sinon.stub(),
+                read: sinon.stub(),
+            };
+            Object.defineProperty(coreWriter, 'ismWriter', {
+                value: mockIsmWriter,
+                writable: true,
+            });
+            // ACT & ASSERT
+            await expect(coreWriter.create(artifact)).to.be.rejectedWith('Mailbox creation failed');
+        });
+    });
+    describe('rateLimited default ISM rejection', () => {
+        // A rateLimited node meters an amount read from a fixed offset of the
+        // message body, which only holds for warp-route traffic — a mailbox
+        // default ISM sees every message.
+        const compositeIsmWithRateLimited = {
+            type: IsmType.COMPOSITE,
+            owner: mockOwner,
+            root: {
+                type: CompositeIsmNodeType.AGGREGATION,
+                threshold: 1,
+                subIsms: [
+                    { type: CompositeIsmNodeType.TEST, accept: true },
+                    {
+                        type: CompositeIsmNodeType.RATE_LIMITED,
+                        maxCapacity: '86400',
+                        mailbox: mockMailboxAddress,
+                    },
+                ],
+            },
+        };
+        const routingIsmWithNestedRateLimited = {
+            type: IsmType.ROUTING,
+            owner: mockOwner,
+            domains: {
+                [mockDomainId]: {
+                    artifactState: ArtifactState.NEW,
+                    config: compositeIsmWithRateLimited,
+                },
+            },
+        };
+        it('rejects it on create before anything is deployed', async () => {
+            // ARRANGE
+            const artifact = {
+                artifactState: ArtifactState.NEW,
+                config: {
+                    owner: mockOwner,
+                    defaultIsm: {
+                        artifactState: ArtifactState.NEW,
+                        config: compositeIsmWithRateLimited,
+                    },
+                    defaultHook: mockDefaultHook,
+                    requiredHook: mockRequiredHook,
+                },
+            };
+            const ismCreateStub = sinon.stub();
+            Object.defineProperty(coreWriter, 'ismWriter', {
+                value: {
+                    create: ismCreateStub,
+                    update: sinon.stub(),
+                    read: sinon.stub(),
+                },
+                writable: true,
+            });
+            // ACT & ASSERT
+            await expect(coreWriter.create(artifact)).to.be.rejectedWith(/rateLimited/);
+            sinon.assert.notCalled(ismCreateStub);
+            sinon.assert.notCalled(createMailboxWriterStub);
+        });
+        it('rejects it when nested inside a routing artifact', async () => {
+            const artifact = {
+                artifactState: ArtifactState.NEW,
+                config: {
+                    owner: mockOwner,
+                    defaultIsm: {
+                        artifactState: ArtifactState.NEW,
+                        config: routingIsmWithNestedRateLimited,
+                    },
+                    defaultHook: mockDefaultHook,
+                    requiredHook: mockRequiredHook,
+                },
+            };
+            const ismCreateStub = sinon.stub();
+            Object.defineProperty(coreWriter, 'ismWriter', {
+                value: {
+                    create: ismCreateStub,
+                    update: sinon.stub(),
+                    read: sinon.stub(),
+                },
+                writable: true,
+            });
+            await expect(coreWriter.create(artifact)).to.be.rejectedWith(/rateLimited/);
+            sinon.assert.notCalled(ismCreateStub);
+            sinon.assert.notCalled(createMailboxWriterStub);
+        });
+        it('rejects it on update before any transaction is built', async () => {
+            // ARRANGE
+            const readStub = sinon.stub(coreWriter, 'read');
+            const expectedArtifact = {
+                artifactState: ArtifactState.DEPLOYED,
+                config: {
+                    owner: mockOwner,
+                    defaultIsm: {
+                        artifactState: ArtifactState.NEW,
+                        config: compositeIsmWithRateLimited,
+                    },
+                    defaultHook: mockDefaultHook,
+                    requiredHook: mockRequiredHook,
+                },
+                deployed: { address: mockMailboxAddress, domainId: mockDomainId },
+            };
+            const ismCreateStub = sinon.stub();
+            const ismUpdateStub = sinon.stub();
+            Object.defineProperty(coreWriter, 'ismWriter', {
+                value: {
+                    create: ismCreateStub,
+                    update: ismUpdateStub,
+                    read: sinon.stub(),
+                },
+                writable: true,
+            });
+            // ACT & ASSERT
+            await expect(coreWriter.update(expectedArtifact)).to.be.rejectedWith(/rateLimited/);
+            sinon.assert.notCalled(readStub);
+            sinon.assert.notCalled(ismCreateStub);
+            sinon.assert.notCalled(ismUpdateStub);
+        });
+        it('accepts a composite default ISM without a rateLimited node', async () => {
+            // ARRANGE
+            const artifact = {
+                artifactState: ArtifactState.NEW,
+                config: {
+                    owner: mockOwner,
+                    defaultIsm: {
+                        artifactState: ArtifactState.NEW,
+                        config: {
+                            type: IsmType.COMPOSITE,
+                            owner: mockOwner,
+                            root: { type: CompositeIsmNodeType.TEST, accept: true },
+                        },
+                    },
+                    defaultHook: mockDefaultHook,
+                    requiredHook: mockRequiredHook,
+                },
+            };
+            const ismCreateStub = sinon.stub().resolves([mockIsm, [mockReceipt]]);
+            Object.defineProperty(coreWriter, 'ismWriter', {
+                value: {
+                    create: ismCreateStub,
+                    update: sinon.stub(),
+                    read: sinon.stub(),
+                },
+                writable: true,
+            });
+            const mockHookWriter = {
+                create: sinon.stub(),
+                update: sinon.stub().resolves([]),
+                read: sinon.stub(),
+            };
+            mockHookArtifactManager.createWriter = sinon
+                .stub()
+                .returns(mockHookWriter);
+            // ACT
+            const [result] = await coreWriter.create(artifact);
+            // ASSERT
+            expect(result.mailbox.deployed.address).to.equal(mockMailboxAddress);
+            sinon.assert.calledOnce(ismCreateStub);
+        });
+    });
+    describe('update', () => {
+        it('should handle ISM type change by deploying new ISM', async () => {
+            // ARRANGE
+            const currentMailbox = {
+                artifactState: ArtifactState.DEPLOYED,
+                config: {
+                    owner: mockOwner,
+                    defaultIsm: mockIsm,
+                    defaultHook: mockDefaultHook,
+                    requiredHook: mockRequiredHook,
+                },
+                deployed: { address: mockMailboxAddress, domainId: mockDomainId },
+            };
+            sinon.stub(coreWriter, 'read').resolves(currentMailbox);
+            const newIsm = {
+                artifactState: ArtifactState.DEPLOYED,
+                config: {
+                    type: IsmType.MESSAGE_ID_MULTISIG,
+                    validators: ['0xVALIDATOR2'],
+                    threshold: 1,
+                },
+                deployed: { address: mockNewIsmAddress },
+            };
+            const expectedArtifact = {
+                artifactState: ArtifactState.DEPLOYED,
+                config: {
+                    owner: mockOwner,
+                    defaultIsm: {
+                        artifactState: ArtifactState.NEW,
+                        config: newIsm.config,
+                    },
+                    defaultHook: mockDefaultHook,
+                    requiredHook: mockRequiredHook,
+                },
+                deployed: { address: mockMailboxAddress, domainId: mockDomainId },
+            };
+            const ismCreateStub = sinon
+                .stub()
+                .callsFake(async () => [newIsm, [mockReceipt]]);
+            const mockIsmWriter = {
+                create: ismCreateStub,
+                update: sinon.stub(),
+                read: sinon.stub(),
+            };
+            mockIsmArtifactManager.createWriter = sinon.stub().returns(mockIsmWriter);
+            const mockHookWriter = {
+                create: sinon.stub(),
+                update: sinon.stub().resolves([]),
+                read: sinon.stub(),
+            };
+            mockHookArtifactManager.createWriter = sinon
+                .stub()
+                .returns(mockHookWriter);
+            // ACT
+            await coreWriter.update(expectedArtifact);
+            // ASSERT
+            sinon.assert.calledOnce(ismCreateStub);
+            const createArg = ismCreateStub.firstCall.args[0];
+            expect(createArg.artifactState).to.equal(ArtifactState.NEW);
+            expect(createArg.config.type).to.equal(IsmType.MESSAGE_ID_MULTISIG);
+        });
+        it('should handle UNDERIVED ISM by using address as-is', async () => {
+            // ARRANGE
+            const currentMailbox = {
+                artifactState: ArtifactState.DEPLOYED,
+                config: {
+                    owner: mockOwner,
+                    defaultIsm: mockIsm,
+                    defaultHook: mockDefaultHook,
+                    requiredHook: mockRequiredHook,
+                },
+                deployed: { address: mockMailboxAddress, domainId: mockDomainId },
+            };
+            sinon.stub(coreWriter, 'read').resolves(currentMailbox);
+            const expectedArtifact = {
+                artifactState: ArtifactState.DEPLOYED,
+                config: {
+                    owner: mockOwner,
+                    defaultIsm: {
+                        artifactState: ArtifactState.UNDERIVED,
+                        deployed: { address: mockIsmAddress },
+                    },
+                    defaultHook: mockDefaultHook,
+                    requiredHook: mockRequiredHook,
+                },
+                deployed: { address: mockMailboxAddress, domainId: mockDomainId },
+            };
+            const ismCreateStub = sinon.stub();
+            const ismUpdateStub = sinon.stub();
+            const mockIsmWriter = {
+                create: ismCreateStub,
+                update: ismUpdateStub,
+                read: sinon.stub(),
+            };
+            Object.defineProperty(coreWriter, 'ismWriter', {
+                value: mockIsmWriter,
+                writable: true,
+            });
+            const mockHookWriter = {
+                create: sinon.stub(),
+                update: sinon.stub().resolves([]),
+                read: sinon.stub(),
+            };
+            mockHookArtifactManager.createWriter = sinon
+                .stub()
+                .returns(mockHookWriter);
+            // ACT
+            await coreWriter.update(expectedArtifact);
+            // ASSERT
+            sinon.assert.notCalled(ismCreateStub);
+            sinon.assert.notCalled(ismUpdateStub);
+        });
+        it('should return empty array when no updates needed', async () => {
+            // ARRANGE
+            const currentMailbox = {
+                artifactState: ArtifactState.DEPLOYED,
+                config: {
+                    owner: mockOwner,
+                    defaultIsm: mockIsm,
+                    defaultHook: mockDefaultHook,
+                    requiredHook: mockRequiredHook,
+                },
+                deployed: { address: mockMailboxAddress, domainId: mockDomainId },
+            };
+            sinon.stub(coreWriter, 'read').resolves(currentMailbox);
+            const expectedArtifact = {
+                artifactState: ArtifactState.DEPLOYED,
+                config: currentMailbox.config,
+                deployed: { address: mockMailboxAddress, domainId: mockDomainId },
+            };
+            const mockIsmWriter = {
+                create: sinon.stub(),
+                update: sinon.stub().resolves([]),
+                read: sinon.stub(),
+            };
+            Object.defineProperty(coreWriter, 'ismWriter', {
+                value: mockIsmWriter,
+                writable: true,
+            });
+            const mockHookWriter = {
+                create: sinon.stub(),
+                update: sinon.stub().resolves([]),
+                read: sinon.stub(),
+            };
+            mockHookArtifactManager.createWriter = sinon
+                .stub()
+                .returns(mockHookWriter);
+            // ACT
+            const result = await coreWriter.update(expectedArtifact);
+            // ASSERT
+            expect(result).to.be.an('array').with.lengthOf(0);
+        });
+        it('should deploy NEW ISM when current is zero-address UNDERIVED', async () => {
+            // ARRANGE
+            const currentMailbox = {
+                artifactState: ArtifactState.DEPLOYED,
+                config: {
+                    owner: mockOwner,
+                    defaultIsm: {
+                        artifactState: ArtifactState.UNDERIVED,
+                        deployed: { address: ZERO_ADDRESS_HEX_32 },
+                    },
+                    defaultHook: mockDefaultHook,
+                    requiredHook: mockRequiredHook,
+                },
+                deployed: { address: mockMailboxAddress, domainId: mockDomainId },
+            };
+            sinon.stub(coreWriter, 'read').resolves(currentMailbox);
+            const newIsm = {
+                artifactState: ArtifactState.DEPLOYED,
+                config: {
+                    type: IsmType.MERKLE_ROOT_MULTISIG,
+                    validators: ['0xVALIDATOR1'],
+                    threshold: 1,
+                },
+                deployed: { address: mockNewIsmAddress },
+            };
+            const expectedArtifact = {
+                artifactState: ArtifactState.DEPLOYED,
+                config: {
+                    owner: mockOwner,
+                    defaultIsm: {
+                        artifactState: ArtifactState.NEW,
+                        config: newIsm.config,
+                    },
+                    defaultHook: mockDefaultHook,
+                    requiredHook: mockRequiredHook,
+                },
+                deployed: { address: mockMailboxAddress, domainId: mockDomainId },
+            };
+            const ismCreateStub = sinon
+                .stub()
+                .callsFake(async () => [newIsm, [mockReceipt]]);
+            const mockIsmWriter = {
+                create: ismCreateStub,
+                update: sinon.stub(),
+                read: sinon.stub(),
+            };
+            Object.defineProperty(coreWriter, 'ismWriter', {
+                value: mockIsmWriter,
+                writable: true,
+            });
+            const mockHookWriter = {
+                create: sinon.stub(),
+                update: sinon.stub().resolves([]),
+                read: sinon.stub(),
+            };
+            mockHookArtifactManager.createWriter = sinon
+                .stub()
+                .returns(mockHookWriter);
+            // ACT
+            const result = await coreWriter.update(expectedArtifact);
+            // ASSERT
+            sinon.assert.calledOnce(ismCreateStub);
+            expect(result).to.be.an('array');
+        });
+        it('should assert artifacts are expanded before updating', async () => {
+            // ARRANGE
+            const currentMailbox = {
+                artifactState: ArtifactState.DEPLOYED,
+                config: {
+                    owner: mockOwner,
+                    defaultIsm: {
+                        artifactState: ArtifactState.UNDERIVED,
+                        deployed: { address: mockIsmAddress },
+                    },
+                    defaultHook: mockDefaultHook,
+                    requiredHook: mockRequiredHook,
+                },
+                deployed: { address: mockMailboxAddress, domainId: mockDomainId },
+            };
+            sinon.stub(coreWriter, 'read').resolves(currentMailbox);
+            const expectedArtifact = {
+                artifactState: ArtifactState.DEPLOYED,
+                config: {
+                    owner: mockOwner,
+                    defaultIsm: mockIsm,
+                    defaultHook: mockDefaultHook,
+                    requiredHook: mockRequiredHook,
+                },
+                deployed: { address: mockMailboxAddress, domainId: mockDomainId },
+            };
+            // ACT & ASSERT
+            await expect(coreWriter.update(expectedArtifact)).to.be.rejectedWith('Expected defaultIsm to be DEPLOYED or UNDERIVED with zero address');
+        });
+        it('should deploy NEW hook during update', async () => {
+            // ARRANGE
+            const currentMailbox = {
+                artifactState: ArtifactState.DEPLOYED,
+                config: {
+                    owner: mockOwner,
+                    defaultIsm: mockIsm,
+                    defaultHook: {
+                        artifactState: ArtifactState.UNDERIVED,
+                        deployed: { address: ZERO_ADDRESS_HEX_32 },
+                    },
+                    requiredHook: mockRequiredHook,
+                },
+                deployed: { address: mockMailboxAddress, domainId: mockDomainId },
+            };
+            sinon.stub(coreWriter, 'read').resolves(currentMailbox);
+            const newDefaultHook = {
+                artifactState: ArtifactState.DEPLOYED,
+                config: { type: 'merkleTreeHook' },
+                deployed: { address: mockDefaultHookAddress },
+            };
+            const expectedArtifact = {
+                artifactState: ArtifactState.DEPLOYED,
+                config: {
+                    owner: mockOwner,
+                    defaultIsm: mockIsm,
+                    defaultHook: {
+                        artifactState: ArtifactState.NEW,
+                        config: newDefaultHook.config,
+                    },
+                    requiredHook: mockRequiredHook,
+                },
+                deployed: { address: mockMailboxAddress, domainId: mockDomainId },
+            };
+            const mockIsmWriter = {
+                create: sinon.stub(),
+                update: sinon.stub().resolves([]),
+                read: sinon.stub(),
+            };
+            Object.defineProperty(coreWriter, 'ismWriter', {
+                value: mockIsmWriter,
+                writable: true,
+            });
+            const hookCreateStub = sinon
+                .stub()
+                .callsFake(async () => [newDefaultHook, [mockReceipt]]);
+            const mockHookWriter = {
+                create: hookCreateStub,
+                update: sinon.stub().resolves([]),
+                read: sinon.stub(),
+            };
+            mockHookArtifactManager.createWriter = sinon
+                .stub()
+                .returns(mockHookWriter);
+            // ACT
+            await coreWriter.update(expectedArtifact);
+            // ASSERT
+            sinon.assert.calledOnce(hookCreateStub);
+        });
+        it('should handle owner change', async () => {
+            // ARRANGE
+            const newOwner = '0xNEWOWNER';
+            const currentMailbox = {
+                artifactState: ArtifactState.DEPLOYED,
+                config: {
+                    owner: mockOwner,
+                    defaultIsm: mockIsm,
+                    defaultHook: mockDefaultHook,
+                    requiredHook: mockRequiredHook,
+                },
+                deployed: { address: mockMailboxAddress, domainId: mockDomainId },
+            };
+            sinon.stub(coreWriter, 'read').resolves(currentMailbox);
+            const expectedArtifact = {
+                artifactState: ArtifactState.DEPLOYED,
+                config: {
+                    owner: newOwner,
+                    defaultIsm: mockIsm,
+                    defaultHook: mockDefaultHook,
+                    requiredHook: mockRequiredHook,
+                },
+                deployed: { address: mockMailboxAddress, domainId: mockDomainId },
+            };
+            const mockIsmWriter = {
+                create: sinon.stub(),
+                update: sinon.stub().resolves([]),
+                read: sinon.stub(),
+            };
+            Object.defineProperty(coreWriter, 'ismWriter', {
+                value: mockIsmWriter,
+                writable: true,
+            });
+            const mockHookWriter = {
+                create: sinon.stub(),
+                update: sinon.stub().resolves([]),
+                read: sinon.stub(),
+            };
+            mockHookArtifactManager.createWriter = sinon
+                .stub()
+                .returns(mockHookWriter);
+            // ACT
+            await coreWriter.update(expectedArtifact);
+            // ASSERT
+            const mailboxWriter = createMailboxWriterStub.returnValues[0];
+            const updatedArtifact = mailboxWriter.update.firstCall.args[0];
+            expect(updatedArtifact.config.owner).to.equal(newOwner);
+        });
+        it('should wire correct addresses into mailbox update', async () => {
+            // ARRANGE
+            const newIsm = {
+                artifactState: ArtifactState.DEPLOYED,
+                config: {
+                    type: IsmType.MESSAGE_ID_MULTISIG,
+                    validators: ['0xVALIDATOR2'],
+                    threshold: 1,
+                },
+                deployed: { address: mockNewIsmAddress },
+            };
+            const currentMailbox = {
+                artifactState: ArtifactState.DEPLOYED,
+                config: {
+                    owner: mockOwner,
+                    defaultIsm: mockIsm,
+                    defaultHook: mockDefaultHook,
+                    requiredHook: mockRequiredHook,
+                },
+                deployed: { address: mockMailboxAddress, domainId: mockDomainId },
+            };
+            sinon.stub(coreWriter, 'read').resolves(currentMailbox);
+            const expectedArtifact = {
+                artifactState: ArtifactState.DEPLOYED,
+                config: {
+                    owner: mockOwner,
+                    defaultIsm: {
+                        artifactState: ArtifactState.NEW,
+                        config: newIsm.config,
+                    },
+                    defaultHook: mockDefaultHook,
+                    requiredHook: mockRequiredHook,
+                },
+                deployed: { address: mockMailboxAddress, domainId: mockDomainId },
+            };
+            const ismCreateStub = sinon
+                .stub()
+                .callsFake(async () => [newIsm, [mockReceipt]]);
+            const mockIsmWriter = {
+                create: ismCreateStub,
+                update: sinon.stub(),
+                read: sinon.stub(),
+            };
+            mockIsmArtifactManager.createWriter = sinon.stub().returns(mockIsmWriter);
+            const mockHookWriter = {
+                create: sinon.stub(),
+                update: sinon.stub().resolves([]),
+                read: sinon.stub(),
+            };
+            mockHookArtifactManager.createWriter = sinon
+                .stub()
+                .returns(mockHookWriter);
+            // ACT
+            await coreWriter.update(expectedArtifact);
+            // ASSERT
+            const mailboxWriter = createMailboxWriterStub.returnValues[0];
+            const updatedArtifact = mailboxWriter.update.firstCall.args[0];
+            expect(updatedArtifact.config.defaultIsm.deployed.address).to.equal(mockNewIsmAddress);
+            expect(updatedArtifact.config.defaultHook.deployed.address).to.equal(mockDefaultHookAddress);
+            expect(updatedArtifact.config.requiredHook.deployed.address).to.equal(mockRequiredHookAddress);
+        });
+        it('should forward expected contractVersion into the mailbox update artifact', async () => {
+            // ARRANGE
+            const expectedContractVersion = '2.0.0';
+            const currentMailbox = {
+                artifactState: ArtifactState.DEPLOYED,
+                config: {
+                    owner: mockOwner,
+                    defaultIsm: mockIsm,
+                    defaultHook: mockDefaultHook,
+                    requiredHook: mockRequiredHook,
+                    contractVersion: '1.0.0',
+                },
+                deployed: { address: mockMailboxAddress, domainId: mockDomainId },
+            };
+            sinon.stub(coreWriter, 'read').resolves(currentMailbox);
+            const expectedArtifact = {
+                artifactState: ArtifactState.DEPLOYED,
+                config: {
+                    owner: mockOwner,
+                    defaultIsm: mockIsm,
+                    defaultHook: mockDefaultHook,
+                    requiredHook: mockRequiredHook,
+                    contractVersion: expectedContractVersion,
+                },
+                deployed: { address: mockMailboxAddress, domainId: mockDomainId },
+            };
+            const mockIsmWriter = {
+                create: sinon.stub(),
+                update: sinon.stub().resolves([]),
+                read: sinon.stub(),
+            };
+            mockIsmArtifactManager.createWriter = sinon.stub().returns(mockIsmWriter);
+            const mockHookWriter = {
+                create: sinon.stub(),
+                update: sinon.stub().resolves([]),
+                read: sinon.stub(),
+            };
+            mockHookArtifactManager.createWriter = sinon
+                .stub()
+                .returns(mockHookWriter);
+            // ACT
+            await coreWriter.update(expectedArtifact);
+            // ASSERT
+            const mailboxWriter = createMailboxWriterStub.returnValues[0];
+            const updatedArtifact = mailboxWriter.update.firstCall.args[0];
+            expect(updatedArtifact.config.contractVersion).to.equal(expectedContractVersion);
+        });
+    });
+});
+//# sourceMappingURL=core-writer.test.js.map