Smart Contracts

Hinkal Protocol — Contracts Overview

This page summarizes the core contracts and how they interact to enable private transactions, external DeFi integrations, and modular execution logic.

Core Orchestration

• Hinkal (contracts/Hinkal.sol)

  • Entrypoint for users. Verifies Groth16 proofs via VerifierFacade, enforces Merkle root membership, slippage and balance invariants, and coordinates hooks and logic calls.

  • Delegates complex execution to HinkalInLogic and writes commitments/nullifiers via HinkalBase.

• HinkalBase (contracts/HinkalBase.sol)

  • Holds canonical state: Merkle tree of commitments and spent nullifiers.

  • Emits NewCommitment/Nullified with semantics for off-chain vs on-chain UTXOs.

  • Provides Transferer helpers and access control for helper/logic addresses.

Logic Layer

• HinkalInLogicBase / HinkalInLogic

  • Implements internal approval UTXO lifecycle, external action execution, and proofless deposit fund handling.

  • inHinkalTransact routes: ONLY_APPROVAL, EXECUTE.

  • inHinkalExecutionFlow spends approvals, executes external calls safely, reconciles balances/allowances, forms UTXOs, and enforces invariants.

  • External action path: handleRunExternalAction prepares deltas and invokes adapter’s runAction.

Policy/Preflight

• HinkalHelper (libs/hardhat/contracts/HinkalHelper.sol)

  • Relay whitelisting and fee policy (RelayStore), token limits and registry (ERC20TokenRegistry), and circuit input construction (CircomDataBuilder).

  • Validates transaction dimensions, sender/relay consistency, calldata hash, gas token usage, access token rules, and EIP-712 EXECUTE metadata.

  • Mints access tokens on demand when signatures are present.

External Integrations

• ExternalActionSwap and Adapters

  • ExternalActionSwap executes a single swap against a router and returns one UTXO. Handles input/output fee deductions and ETH wrapping.

  • UniswapExternalAction: Uniswap V3 exactInputSingle using encoded fee tier.

  • OneInchExternalAction: Executes raw calldata from 1inch API; computes output by balance delta.

  • OdosExternalAction: Executes Odos calldata; expects output amount in return data.

• Emporium

  • Upgradeable, batch-execution external action. Decodes EmporiumStack (signed when stateful) and runs operations either via direct calls or through a user’s HinkalWallet.

  • Anti-replay with usedMessages, EIP-712 signature binding, per-token accounting with delta adjustments, and relay fee payment.

• HinkalWallet

  • Minimal, Emporium-controlled wallet supporting stateful sequences.

  • Exposes strictly gated calls (callHinkalWallet, doSendToRelay) and EIP-1271 for signature verification.

Typical Flow (transact)

1. Client builds CircomData, generates proof, and submits transact.

2. Hinkal calls HinkalHelper.performHinkalChecks → returns circuit public signals.

3. verifyProof and rootHashExists gates pass.

4. Optional hooks run; approvals processed if requested.

5. Execution branch:

   • Internal deposit/withdrawal

   • In-logic execution (spend approvals, external call, reconcile)

   • External action adapter (e.g., Uniswap/1inch/Odos)

6. Slippage and balance equations enforced per token.

7. Nullifiers inserted; commitments added; events emitted for indexers.