Entrypoints

Entrypoints are the only user-facing contracts in Shinobi Cash.
They coordinate proof verification, intent creation, and crosschain fund movement by interacting with pools, settlers, and oracles.

Design Principle

Shinobi separates entrypoints by authority domain.

Users always interact with the entrypoint on the chain where they currently hold funds. Entrypoints do not custody funds — funds flow through to settlers in the same transaction.

ShinobiCashEntrypoint (Pool Chain)

The canonical orchestrator on the pool chain.
Extends the base Entrypoint from privacy-pools-core.

Responsibilities

• Crosschain withdrawals
  • Verifies ZK proof via the pool
  • Creates OIF withdrawal intent
  • Escrows funds for solver settlement
• Crosschain deposits
  • Accepts verified deposit fills from ShinobiDepositOutputSettler
  • Inserts commitments into the pool
• Refund handling
  • Accepts expired withdrawal intents from ShinobiInputSettler
  • Inserts refund commitments into the pool
• Same-chain withdrawals
  • withdraw2: spends two notes on the pool chain
  • crosschainWithdraw2: spends two notes and exits crosschain

Access Control

• Withdrawal functions are permissionless (valid proof required)
• Crosschain deposit handler callable only by ShinobiDepositOutputSettler
• Refund handler callable only by ShinobiInputSettler

ShinobiCrosschainDepositEntrypoint (Origin Chains)

Entrypoint deployed on non-pool chains where users hold assets.

Responsibilities

• Crosschain deposits
  • Accepts funds and a precommitment
  • Creates an OIF deposit intent
  • Escrows funds in ShinobiInputSettler
  • Submits intent proof to the pool chain via Hyperlane
• Refund initiation
  • Proxies refund requests for expired deposit intents
  • Refund execution remains permissionless via InputSettler

Deposit Flow

1. User calls deposit() with funds and a precommitment
2. Entrypoint creates an OIF intent and escrows funds in InputSettler
3. Intent proof is relayed to the pool chain
4. Solver fills the intent via ShinobiDepositOutputSettler
5. Solver claims escrowed funds after proving the fill

Precommitments

Both entrypoints require a precommitment derived from the user’s secret.

Precommitments:

• are marked as used on first submission
• cannot be reused on the same chain
• prevent replay and duplicate intent creation

Precommitments do not reveal note secrets or link deposits and withdrawals.

Security Notes

• Entrypoints do not custody funds (funds flow through to settlers)
• All withdrawals require valid ZK proofs
• Crosschain actions are finalized only via settler + oracle validation
• Entrypoints are not trusted for correctness beyond enforcing invariants

Source Code

• ShinobiCashEntrypoint
• ShinobiCrosschainDepositEntrypoint

Related

• Privacy Pool — Proof validation and commitment management
• Shinobi x OIF — Crosschain settlement logic
• Crosschain Architecture — End-to-end system flow