AI-assisted Smart Contract Engineering - From Acceleration to Assurance

AI-assisted smart contract engineering: from acceleration to assurance

Smart contracts are executable product architecture

At Ikigai, we have always treated Vault Core smart contracts as more than product implementation code. They are executable product architecture.

In a thin-core architecture, smart contracts carry much of the product logic that would traditionally be buried inside a core banking system. They define how financial products behave through time: how balances move, how schedules fire, how fees are charged, how postings are generated, how lifecycle events are handled, plus how customer outcomes are produced.

That is powerful, but it also creates responsibility.

A smart contract estate cannot be judged only by whether each product works in isolation. It also depends on whether product logic is structured deliberately: whether features are reusable, whether schedules follow consistent patterns, whether tests prove behaviour directly, whether features can be composed safely, plus whether future change can happen without rediscovering the same engineering problems.

The temptation in any individual product delivery is to optimise for local speed. But in a real core banking programme, the same concerns appear repeatedly across products: schedules, accruals, fees, due amount calculation, date handling, posting rules, notifications, lifecycle events, test setup, plus migration paths.

If every product solves these concerns differently, the codebase becomes expensive very quickly. The problem is not only duplication. The deeper problem is accidental architecture.

A product can pass its tests, go live, then still create long-term cost if its patterns cannot be reused, reasoned about, or safely changed. Every future product then inherits hidden work: developers have to rediscover the same patterns, avoid the same timing problems, wire the same configuration, then rebuild confidence from scratch.

Smart contract delivery should be built around reusable architecture, strong behavioural tests, plus intentional engineering patterns that can be applied consistently across products, not heroics product by product.

Reuse needs more than shared code

Reuse in smart contract engineering is often misunderstood as a code extraction problem. Extract a few helper functions, create a few reusable feature modules, reduce duplication, job done.

It reduces duplication, but it does not solve the architecture problem.

Real reuse means designing product behaviour so it can be composed safely across products, tested consistently, plus evolved without rebuilding confidence from scratch every time.

Schedules are a good example. They are easy to underestimate because they look like simple timing rules, but they quickly become architecture once reused across products.

The complexity sits less in the timer itself than in how that timer interacts with the rest of the product.

Reusable templates matter because they make these decisions explicit, turning hidden implementation choices into visible product architecture.

A schedule register gives the product a single place where schedule timing plus execution ordering can be understood. Schedule modules give each event a clear boundary. Catalogue templates allow common behaviours such as skipping, offsetting, special runs, or end-of-month handling to be composed deliberately instead of copied manually.

That turns schedule engineering from project-specific plumbing into a reusable architecture pattern.

The same principle applies to the product contract itself. Product hooks should stay thin.

Hooks are runtime entry points. They should make the product lifecycle visible: what happens at activation, what happens on a scheduled event, what happens when postings are generated, what happens when parameters change.

They should not become the place where every calculation, parameter lookup, posting rule, schedule decision, validation, edge case, plus cross-feature interaction is implemented inline.

The product contract should compose the product. It should declare which features exist, wire them into the relevant lifecycle events, then delegate the feature behaviour itself to bounded modules. Some composition belongs directly in the product contract. Some belongs in dedicated orchestrators, especially where multiple features combine into a reusable product behaviour.

That separation keeps the product readable. It also makes reuse more realistic, because the team is not just sharing code fragments. It is building tested product capabilities that can be assembled deliberately across products.

AI turns pattern libraries into assurance systems

Ikigai has always taken the view that writing smart contracts is not the hardest part.

Producing smart contract code is the easier part. Proving that the financial behaviour is correct is where the rare experience sits.

In this context, quality means more than clean code. It means deterministic financial behaviour: schedules firing at the right time, postings being correct, lifecycle events happening in the right order, edge cases covered, race conditions avoided, date handling made safe, intended behaviour proven, unintended behaviour exposed during development, plus future change not quietly breaking existing products.

AI makes this more important, not less.

That speed changes the baseline. Without the right architecture around it, an agent can generate inconsistency just as quickly. It is extremely good at repeating patterns, which is powerful when the patterns are strong, but dangerous when they are weak. It can put logic in the wrong layer, miss lifecycle interactions, duplicate product concepts, bypass test obligations, or produce code that looks reasonable while weakening the long-term quality of the estate, all within seconds.

Historically, pattern libraries, templates, plus accelerators were often positioned around delivery speed. They reduced repeated effort. They helped teams move faster. That still matters, but as AI makes raw code generation increasingly available, the stronger differentiator is quality by design.

A mature pattern library does not just give AI something to copy. It gives AI a tested path to follow. The pattern already encodes implementation structure, known edge cases, schedule behaviour, posting expectations, lifecycle ordering, product configuration choices, plus the test coverage expected around it.

A pattern library still needs an operating model. A well-designed template can still be misapplied by an agent that does not understand the intended structure, test obligations, or failure modes.

Ikigai has therefore invested not only in reusable smart contract templates, but also in specialised AI agents plus skills designed around those templates. That includes agents for smart contract build, testing, refactoring existing contracts into the defined feature architecture, version uplift such as v3 to v4, plus review against hundreds of Ikigai lessons learned from real smart contract engineering work.

Those lessons cover areas such as schedule timing, posting construction, hook design, parameter handling, simulation setup, feature composition, plus common Vault Core failure modes.

The point is not to leave a general-purpose AI agent to guess how a Vault Core smart contract should be structured. The intended application of the pattern has to be explicit: which pattern is being used, where the feature logic should live, what tests are expected, what review checks apply, plus which risks require special attention.

In this model, AI applies tested product architecture through a controlled delivery workflow.

Specialist agents improve consistency, but they do not remove engineering accountability. They make expert review more focused by bringing the code closer to the intended architecture before a human reviews it.

Credibility comes from the combination: reusable patterns, deep behavioural coverage, specialised agents, expert review, plus a lessons-learned loop that keeps the AI aligned with proven engineering practice.

Behavioural proof is the credibility layer

Reusable smart contract architecture is only credible if it is backed by strong behavioural proof. Tests are not a quality afterthought. They are part of the design input: the main way to prove that expected financial behaviour is met exactly.

This matters even more when logic is reused across products. Code that worked in one product does not automatically work in another. Product shape, parameters, timings, posting expectations, boundary cases, customer journeys, plus feature interactions can all change.

Shared code without that proof is dangerous, because financial product logic often fails at the edges: schedule timing, lifecycle transitions, date boundaries, fee interactions, early closure paths, skipped events, plus product-specific parameter combinations. The goal is reusable product behaviour with evidence that it still works in each product context.

That means simulation tests, BDD scenarios, generated expectations, plus test structures that exercise the same core behaviour under different product configurations.

Good tests also prove behaviour directly.

If an internal product event is expected to happen, checking only the final balance is often an indirect proof. The balance may be correct for the wrong reason. Another event may have posted the amount. A later correction may mask the earlier failure. A stronger test asserts the event itself where possible, then separately asserts the financial outcome.

The same principle applies across the product lifecycle. A loan can have the correct final balance while still accruing incorrectly during the term. A product can close correctly at maturity while still behaving incorrectly at the first repayment date. Financial products are lifecycle products, so the test suite needs to prove the lifecycle: origination, first due date, month-end, mid-life behaviour, rate changes, fee events, overdue paths, early closure, maturity, plus the points where multiple rules interact.

Unit tests have a different job from BDD tests. Unit tests prove the parts: calculation rules, edge cases, parameter combinations, small pieces of feature logic. BDD proves the product behaviour: end-to-end behaviour through time, especially where multiple features interact. We explored that testing discipline in more detail in our earlier article on smart contract testing with BDD/Gherkin.

When those layers are blurred, unit tests can become slow simulations in disguise, while BDD scenarios can become overloaded with implementation detail.

For AI-assisted delivery, this kind of coverage is not optional governance. It is the feedback system that tells the agent, plus the engineer reviewing it, whether the product still behaves correctly.

Example: timezone-aware BDD for multi-country products

For banks building global or multi-country products, timezone handling is not a cosmetic detail. The test suite needs to express business time clearly, so that timezone-specific behaviour is made visible from the start.

UTC timestamps are precise, but not always business-readable. In Pacific/Auckland, this timestamp:

2022-01-30T11:00:08Z

means local midnight plus 8 seconds on 31 January.

A better scenario says the timezone explicitly:

Given the account operates in timezone "Pacific/Auckland"

Then local timestamps can be written directly:

2022-01-31T00:00:08

UTC timestamps with Z can still be used where needed, so the notation remains backward-compatible.

The point is not the timestamp format itself. The point is that test architecture should make product behaviour easier to read, easier to review, plus easier to reuse across timezone contexts. For multi-country products, that clarity should exist before timezone handling becomes a production edge case.

Example: schedule templates as tested product capabilities

Schedules are one of the places where smart contract code looks deceptively simple.

At first glance, a schedule is just a timing rule: run daily, monthly, at end of month, or on a specific event date. In a real product, that timing rule sits inside a much wider failure surface. A schedule may need to run after another schedule, skip a run under specific lifecycle conditions, apply a date offset, handle end-of-month behaviour, support catch-up behaviour, respect timezone-specific business time, generate postings, emit notifications, or interact with other product features.

That is why a schedule template is part of the product architecture, not just a timing helper. It carries expected behaviour, wiring conventions, edge cases, plus test obligations.

The test coverage needs to prove both sides: the schedule mechanics and the financial outcome. For example, if a monthly repayment schedule is offset from the contractual due date, the test should prove when the schedule executed, whether any skip or catch-up rule was applied, and what postings or balance changes resulted. A final balance alone is not enough, because it may be correct for the wrong reason.

For AI-assisted delivery, this matters because the agent is not inventing schedule structure from scratch. It is applying a proven pattern that already carries the design decisions, known edge cases, wiring conventions, plus behavioural proof expected around that schedule.

That is what turns the template from an accelerator into an assurance mechanism.

Quality by design

Reuse in smart contract engineering is possible, but it does not happen by accident.

It needs deliberate seams, stable module boundaries, clear ownership, and tests that prove behaviour rather than implementation. That is what turns reusable code into reusable product capability.

AI makes this discipline more valuable, not less. The faster code generation becomes, the more important it is that quality is designed into the delivery system.

The future of AI-assisted smart contract engineering is not just better prompting.

It is quality by design.