4.2.1. Overview
Figure 2 illustrates the interactions among the entities within the zkWill framework. In this architecture, the testator designates an executor to facilitate the transfer of on-chain assets to the beneficiaries. The testamentary document is protected via symmetric encryption using a key shared between the testator and the executor, resulting in a digitally sealed will.
The system subsequently uploads the encrypted file to IPFS, generating a Content Identifier (CID) that it records on the blockchain. A zero-knowledge proof (ZKP) then verifies the authenticity of the testator’s digital signature within the sealed envelope without disclosing its contents.
While the ZKP ensures the technical feasibility of the digital will, the notarization phase guarantees its legal enforceability. Upon the recording of the CID on chain, the notary and witnesses—designated in accordance with Article 1198 of the Civil Code—must notarize the CID to formalize the instrument.
The executor, equipped with the CID and the shared encryption key, retains the capability to retrieve and decrypt the will. To ensure inheritance distribution strictly follows the testator’s intent, zkWill transforms the digitally sealed will into a smart contract. This contract is exclusively triggerable by the designated executor, thereby upholding two fundamental security principles:
However, this architecture does not natively enforce a temporal constraint (i.e., when the transfer can occur). A potential vulnerability exists where an executor might collude with a beneficiary to prematurely execute the asset transfer while the testator is still alive. To mitigate such risks, prior implementations such as CryptoWills and WillChain use periodic “heartbeat” actions; however, such time-based mechanisms remain legally insufficient for determining death in most jurisdictions.
To align with established legal frameworks, the asset transfer must be contingent upon a formal legal confirmation of the testator’s demise.
Given the empirical complexity of death verification, the system delegates this responsibility to an external oracle representing a trusted real-world entity (e.g., a hospital or government agency).
This oracle “probates” the sealed will by providing verified proof of death. Following this probation, the executor deploys the Will contract, accompanied by a secondary ZKP verification to prevent the submission of fraudulent testamentary data. Upon successful deployment, the executor invokes the contract to finalize the estate distribution. Throughout this lifecycle, beneficiaries remain passive recipients, preserving the confidentiality and unilateral nature inherent to a sealed will.
The technical core of the zkWill system is anchored by a pre-deployed WillFactory contract on an EVM-compatible blockchain. The WillFactory serves as the primary orchestration layer, encompassing the following core functionalities:
predictWill(): This function computes the deterministic address of a future Will contract based on the testator’s address, an estate list, and a specific salt value. By leveraging the CREATE2 opcode, the system allows for the pre-computation of contract addresses prior to actual deployment.
uploadCid(): This function enables the testator to upload the Content Identifier (CID) of the sealed will to the blockchain. It concurrently verifies, via a Zero-Knowledge Proof (ZKP), that the file contains a valid digital signature originating from the testator. Access to this function is strictly restricted to the testator.
notarizeCid(): This function facilitates the formal notarization of an uploaded CID by the notary. It requires the submission of digital signatures from at least two witnesses to validate the CID, and access is restricted exclusively to the notary.
probateCid(): This function permits the oracle to perform the “probate” action on a notarized CID. The function is restricted to authorized oracle entities to confirm the legal passing of the testator.
createWill(): This function enables the executor to instantiate the actual Will contract based on a probated CID. The contract is deployed via the CREATE2 opcode to ensure the address matches the previously predicted value. Prior to instantiation, a secondary ZKP is verified to guarantee the integrity of the off-chain decryption process.
During the initialization phase of the WillFactory, the addresses for the JsonCidVerifier and the two specialized ZKP verifier contracts must be provided as constructor parameters. All subsequent validations of CIDs and ZKPs are delegated to these external, modular verifier contracts to ensure system extensibility.
Once successfully deployed, the individual Will contract exposes a singular, critical executable function:
The comprehensive Solidity implementation for both WillFactory.sol and Will.sol is available via a public GitHub repository [
32].
The permissions for each role in the system are described in
Table 2. We assume that the wallet’s private key is not included within the will itself. Consequently, while the executor is granted read access to the will, it has no authorization to modify, revoke, or execute the will.
4.2.2. Details
Phase 1: Testator Lifecycle—Drafting, Encryption, and Zero-Knowledge Anchoring
The inception of the zkWill lifecycle begins with the testator’s synthesis of a structured legal instrument. This digital document is not merely a list of assets but a formalized data structure comprising the testator’s address, the designated executor, and witnesses. As evidenced in
Figure 3, the “estate” is granularly defined; each entry mandates an ERC-20 token contract address, the specific quantum of transfer, and the beneficiary’s cryptographic identity. To bind these intentions to a verifiable signature, the testator issues a “permit”—a cryptographic authorization that bridges the gap between static intent and executable code (detailed in
Section 5.2.1).
The Privacy–Governance Nexus
A notable architectural choice in zkWill is its adaptability to regulatory oversight. By permitting the designation of a tax authority as the executor, the system provides a pathway for institutional estate management, ensuring that asset distribution adheres to inheritance tax obligations.
To safeguard these sensitive data from public exposure, the will undergoes local AES-256-CTR encryption before departing the testator’s environment. We assume a robust key-management framework—leveraging Diffie–Hellman or specialized Key Management Services (KMSs)—to establish a shared secret between the testator and the executor. This “sealed” ciphertext, accompanied by its Initialization Vector (IV), is then relegated to the Inter Planetary File System (IPFS) shown in
Figure 4. This off-chain storage strategy is a pragmatic necessity; given the prohibitive gas costs associated with on-chain data persistence, storing the full ciphertext directly on the blockchain would be economically non-viable for complex estates. Instead, the blockchain acts as a ledger of integrity, storing only the Content Identifier (CID) via the uploadCid() function.
Figure 5 illustrates the complete lifecycle of will creation from the testator’s perspective within the zkWill framework. The process begins with the testator drafting a structured digital will, specifying key roles (executor, witnesses) and detailing estate allocations, including ERC-20 token addresses, transfer amounts, and beneficiary identities.
To ensure a precise technical understanding of
Figure 5, the visual notation must be interpreted through the lens of standard sequence diagram semantics, representing the temporal movement of data, state transitions, and cryptographic transformations within the zkWill Phase 1 lifecycle.
1. Solid Directional Arrows: Sequential Execution Flow
The primary solid arrows delineate the active execution path, signifying a synchronous progression where each operation serves as a prerequisite for the subsequent stage:
From Drafting to Signing: Denotes the transformation of the testator’s subjective intent into machine-readable, cryptographically authorized signatures (Steps 1–6).
From Signing to Encryption: Indicates the encapsulation of the Permit2 authorization within the data payload (Step 7) prior to the application of AES-256-CTR encryption (Step 9), ensuring the "will" is obscured before transmission.
From Encryption to On-Chain Anchoring: Represents the migration of the sealed "blob" and its associated metadata (CID and ZKP) from the local client to the DID-Chain (Step 13).
2. Dashed Arrows: Systemic Return Messages
In contrast to auxiliary inputs, the dashed arrows in this diagram strictly represent Return Signals or asynchronous feedback from the protocol components:
Address Return: The WillFactory provides the testator with a pre-calculated, deterministic contract address via CREATE2 (Step 4).
Transaction Confirmation: Signifies the receipt of a "success" status from the blockchain after the network has validated the user’s digital identity and finalized the session (Step 11).
3. Self-Loop Arrows: On-Chain Integrity Verification
Arrows that cycle back to the same participant (Self-loops) represent internal validation logic executed within the smart contract environment:
Integrity Checks: These represent the DID-Chain recomputing hashes and validating the Phase 1 ZKP against the anchored CID (Steps 14–15). This ensures that no data corruption occurred during the IPFS upload and that the proof is mathematically sound before the state is committed to the ledger.
4. Environmental Architecture: Implicit Boundaries
The distinction between execution environments is established through the horizontal positioning of participants (Lifelines) rather than physical boundary lines:
Off-Chain Domain (Testator): The leftmost section encapsulates private, client-side computations (e.g., drafting and local encryption) where sensitive data remains isolated from the public ledger.
On-Chain Domain (DID-Chain / WillFactory): The central columns represent the decentralized execution environment where gas-consuming transactions occur.
Post-Anchoring Key Handover: Crucially, the Key Transfer (Step 16) is depicted as the final operation, occurring only after successful on-chain anchoring. This signifies a private, off-chain handover of the decryption secret to the Executor, ensuring that access control is only delegated once the testamentary record is immutably secured.
Once finalized, the testator cryptographically signs the will by generating a permit, transforming the document from static intent into an executable authorization compatible with smart contract logic.
To preserve confidentiality, the signed will is then encrypted locally using AES-256-CTR. A shared secret key is established between the testator and the designated executor through secure key exchange mechanisms (e.g., Diffie–Hellman or a Key Management Service), ensuring that only authorized parties can decrypt the contents.
Following encryption, the ciphertext—along with its initialization vector (IV)—is uploaded to IPFS for decentralized off-chain storage. This step minimizes on-chain costs while maintaining data availability. Finally, the resulting Content Identifier (CID) is anchored on-chain via a function such as uploadCid(), enabling verifiable integrity without exposing sensitive information.
Overall, the figure captures a pipeline of four key stages, drafting, signing, encryption, and decentralized storage with on-chain anchoring, demonstrating how zkWill balances privacy, cost-efficiency, and verifiability.
The architectural necessity for privacy-preserving and compliant frameworks is further underscored in the recent literature. For instance, research on LLM deployment in regulated enterprise AI systems [
33] proposes a modular approach to meet stringent GDPR and HIPAA requirements without sacrificing system utility. This aligns with the zkWill philosophy, where a modular, ZKP-driven architecture is utilized to harmonize the rigid demands of inheritance law with the inherent transparency of blockchain technology, ensuring both statutory compliance and cryptographic privacy.
Cryptographic Integrity and the ZKP Frontier
The JsonCidVerifier contract provides a critical on-chain check-and-balance, recomputing hashes to ensure the CID’s fidelity. However, the system’s true security lies in its Phase 1 ZKP. This proof serves as a mathematical guarantee that the encrypted blob contains a valid signature and all parameters necessary for a future transfer—without ever exposing the underlying plaintext to the public.
A central challenge in this phase is the authorization bottleneck. A primitive design might embed the testator’s private key within the encrypted will, but such an approach is fundamentally flawed. It introduces a catastrophic single point of failure where a compromised executor could unilaterally misappropriate assets. Even the standard approve() function falls short, as it fails to enforce execution constraints or specific beneficiaries.
From ERC-2612 to Permit2: A Shift in Paradigm
To mitigate these systemic vulnerabilities, zkWill utilizes the permit() function (ERC-2612) [
12]. This represents a significant shift from legacy “allowance” models:
Digital Sovereignty: Unlike approve(), permit() utilizes off-chain signatures, minimizing the exposure of private keys and incorporating built-in replay protection.
Delayed Disclosure: Authorizations remain off-chain until the probate phase, effectively masking the token types and amounts from pre-mortem surveillance.
Unified Permissions: Our implementation adopts Permit2, an evolution of the standard that allows for batch transfers and unified permissions across disparate contracts.
As illustrated in
Figure 6, while generating these ZKPs is computationally expensive—often requiring several minutes of high-intensity processing—this temporal cost is a deliberate trade-off. It secures a future where the testator’s assets remain locked in a “silent” yet programmatically certain state until the legal criteria for distribution are met.
Phase 2: Notarization—The Legal–Cryptographic Synthesis
Once the testator’s CID has been anchored and the Phase 1 Zero-Knowledge Proof (ZKP) successfully validated, the system transitions into the Notarization Phase. This stage is not merely a technical checkpoint but a digital translation of physical probate requirements. To align with the stringent mandates of the Civil Code—which demands the contemporaneous presence of the testator, a notary, and at least two witnesses for a sealed will—the zkWill protocol mandates a Multi-Signature (Multi-Sig) Validation Protocol.
Figure 7 depicts the notarization phase, where the zkWill protocol formalizes the will through a legally compliant, multi-party validation process. Following the successful anchoring of the Content Identifier (CID) and verification of the Phase 1 Zero-Knowledge Proof (ZKP), the system advances into a stage that mirrors the procedural rigor of traditional sealed wills.
The architecture ensures that the “sealed” integrity of the instrument is not compromised during this scrutiny. Instead of verifying the contents, the witnesses and the notary verify the testator’s intent and the integrity of the CID. As delineated in
Figure 8, the notarization workflow is structured as a sequence of cryptographically bound attestations:
1. Witness Attestation and Consensus
The designated witnesses are required to provide digital signatures that correspond to the specific CID recorded in Phase 1. This act functions as a distributed affidavit; by signing, witnesses attest that the digital envelope was indeed presented by the testator and remains untampered with since its upload. This prevents “document swapping” attacks where a malicious actor might attempt to notarize a fraudulent CID.
2. Notarial Authentication and Finality
Upon receiving the requisite witness signatures, the notary invokes the notarizeCid() function within the WillFactory contract. This operation acts as the final “seal” on the digital instrument. The contract logic enforces an asymmetric authority constraint: the notary cannot proceed without the verified threshold of witness signatures, thereby programmatically mirroring the collective presence required in a physical notary’s office.
3. Transition to the Immutable State
Once the multi-signature process is finalized, the status of the CID on the blockchain transitions from “Pending” to “Notarized”. This state change is irreversible. This digital “sealing” transcends mere data entry; it anchors the instrument in a state of irreversible legal–technical formalization, effectively bridging the gap between a private draft and a probate-ready document. Unlike traditional paper-based systems—notoriously prone to custodial negligence or the physical loss of records—zkWill utilizes the blockchain as an adversarial-resistant ledger. By doing so, the protocol mitigates the persistent risk of notarial repudiation. This transition ensures that the audit trail is not merely “immutable” in a technical sense but remains judicially robust under the weight of cryptographic proof, providing a level of certainty that standard centralized databases fail to guarantee in a court of law.
Phase 3: Probate—The Oracle-Mediated Mortality Trigger
The transition from a dormant notarized record to an executable instrument represents the most critical security bottleneck in decentralized inheritance. To neutralize the risk of premature asset dissipation—whether through executor–beneficiary collusion or malicious intent—the WillFactory contract enforces a rigorous operational sequence. Specifically, the createWill() function remains cryptographically locked until a formal, verifiable proof of death is anchored to the blockchain.
Figure 9 illustrates the probate phase, where the zkWill protocol activates a notarized will through a secure, oracle-mediated verification of the testator’s death. This stage represents a critical control point, ensuring that asset distribution cannot be triggered prematurely or manipulated by malicious actors.
The Oracle as a Socio-Technical Bridge
The “proof-of-death” is not merely a data point but a legal determination fraught with jurisdictional nuances. While a granular legal analysis of death certification lies outside this technical scope, the zkWill architecture acknowledges this complexity by delegating the verification to an Oracle. This entity functions as the essential bridge between off-chain civil registries and on-chain state transitions.
In our framework, as depicted in
Figure 10, this oracle may manifest as a specialized smart contract or a permissioned Externally Owned Account (EOA). The system treats the oracle as a trusted sentinel, whose sole responsibility is to validate external legal events and authorize the “Probated” state transition.
Procedural Enforcement and State Finality
Rather than a simple linear checklist, the execution workflow is an interlocking state machine:
Verifiable Confirmation: The process begins not with a trigger, but with an evidentiary audit. The oracle must verify the authenticity of the death certificate or government-issued notification before any on-chain action is taken.
Irreversible State Transition (probateWill): Only upon successful verification does the oracle invoke the probateWill() function. This act transitions the digital will’s status to “Probated”—a state change that is globally visible yet immutable.
The Activation Gateway: Crucially, the createWill() function is dormant by design; its accessibility is strictly contingent upon this prior state transition. Only after the oracle has “unlocked” the probate status can the executor initiate the deployment of the Will.sol contract and proceed with asset distribution.
This tiered authorization model ensures that the testator’s assets remain under sovereign control until the exact moment the legal criteria for succession are satisfied, effectively eliminating the “living executor” vulnerability.
Phase 4: Execution—Deterministic Asset Distribution and Executor Disintermediation
The final phase is triggered only when the testator’s legal demise is anchored on chain, transitioning the protocol from a state of preservation to one of active enforcement. The executor initiates the process by retrieving the ciphertext from IPFS via its unique CID. Crucially, the decryption occurs within a local, off-chain environment using the pre-established shared secret; this ensures that the plaintext—the most sensitive component of the estate—is never exposed to the public mempool before the execution logic is finalized.
Figure 11 illustrates the execution phase, where the zkWill protocol transitions from passive state preservation to active enforcement of the testator’s final intentions. This phase is triggered only after the testator’s death has been formally verified and anchored on chain, unlocking the conditions required for execution.
1. The Verification Paradox: ZKP as an Integrity Anchor
To prevent the executor from altering the will’s parameters during the transition from ciphertext to contract, the createWill() function mandates a Phase 2 Zero-Knowledge Proof (ZKP). This proof resolves a fundamental trust issue: it mathematically guarantees that the submitted plaintext is the faithful and untampered result of decrypting the CID-linked ciphertext.
Hash Link Integrity: The ZKP ensures the encrypted blob matches the on-chain CID perfectly.
Authentic Decryption: It verifies that the plaintext instructions presented to the blockchain are exactly what the testator sealed, effectively stripping the executor of any discretionary power to modify transfer amounts or beneficiary addresses.
2. Programmatic Finality via Smart Contract Metamorphosis
Once the ZKP is verified, the WillFactory performs a “metamorphosis,” transforming the static plaintext into a bespoke, immutable smart contract (Will.sol). Unlike traditional executors who might exercise personal judgment—or succumb to external pressure—this contract hardcodes the testator’s mandates (token quanta and recipient identities) directly into its bytecode at deployment.
The transfer of assets is subsequently governed by a tripartite security logic:
Restricted Agency: The signatureTransferToBeneficiaries() function is hardcoded with strict Access Control, accessible solely to the designated executor.
Cryptographic Authorization: The executor cannot simply “send” funds; they must provide the specific Permit2 signature generated by the testator in Phase 1.
Atomic Execution: The Permit2.sol contract acts as the ultimate arbiter, executing the permitTransferFrom() call only if the signature, the deadline, and the transfer rules align with the pre-defined on-chain state.
3. Security Analysis: The “Automated Relay” Model
As reflected in the executor’s interface (
Figure 12), the zkWill architecture enforces a radical Least Privilege model. By the time Phase 4 commences, the executor is reduced to a “technical relay”—an entity responsible for initiating transactions and subsidizing gas fees, yet possessing zero technical capability to deviate from the original intent. Even in a scenario where the executor’s environment is compromised, the attacker finds no “write” access to the will’s logic; they are bound by the immutable parameters of the Will.sol contract and the cryptographic constraints of the Permit2 signature. This design achieves a rare equilibrium: the flexibility of off-chain drafting combined with the absolute, trustless finality of on-chain execution.