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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://hinkal-team.gitbook.io/hinkal/technical-description/smart-contracts.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.