Tenebrae SDK V2
Positioning
Tenebrae SDK V2 is the integrator product surface for wallet-signed private settlement on public EVM chains.
| We say | We do not say |
|---|---|
| SDK V2 uses explicit prepare → prove → submit embed patterns | Third-party Host brand as the product story |
| SDK V2 includes Confidential DeFi journey interfaces (swap · supply · borrow) | DeFi on mainnet production |
| Institutional default remains Tenebrae client + BYOW | Tenebrae is a wallet or WaaS |
Public Integrate leads with SDK V2 — the same product surface for app embeds and Kohaku-class wallet Host shells. Packaging (client · embed · white-label): How to adopt. Embed literacy: embed patterns.
What ships in the mental model today
| Capability | Maturity |
|---|---|
| Deposit into Tenebrae · private transfer · withdraw from Tenebrae | Testnet hosts |
runSettlement(journey) spine | Settlement subsystem (RFC 0020) |
| Policy predicates in every Protocol settle | Architecture — not market clearance |
| Private DeFi (adapt-batch · positions) | In product on sandbox — Stack · Confidential DeFi below |
| Wallet Host adapter (Kohaku-class shells) | Testnet package — Wallet Host distribution below |
Layers
Your wallet (BYOW / custody signer)
↓
Tenebrae SDK V2 ─── prepare · prove · submit · receipts
↓
@tenebra/shared settlement (`runSettlement`)
↓
Tenebrae Protocol (Gateway entry · hubs · proofs)
Exact npm package entrypoints move with refactors — confirm against package READMEs after upgrade.
Preliminary interface — core settlement
Illustrative TypeScript. Product labels: Deposit into Tenebrae · Private transfer · Withdraw from Tenebrae.
/** Core settlement — Protocol-backed. */
export interface ITenebraeSdkV2Settlement {
/** Deposit into Tenebrae — public wallet → Protocol private settlement. Amount public on-chain. */
prepareDeposit(args: IPrepareDepositArgs): Promise<IPreparedSettlement>;
/** Private transfer — stays inside Protocol private settlement. */
prepareTransfer(args: IPrepareTransferArgs): Promise<IPreparedSettlement>;
/** Withdraw from Tenebrae — Protocol private settlement → public wallet. Amount public on-chain. */
prepareWithdraw(args: IPrepareWithdrawArgs): Promise<IPreparedSettlement>;
/** Unified prove + transport (RFC 0020). */
runSettlement(journey: ISettlementJourney): Promise<ISettlementResult>;
/** Private balance projection for the connected asset owner. */
getPrivateBalance(args: IPrivateBalanceArgs): Promise<IPrivateBalanceView>;
}
type SettlementStepKind =
| 'deposit'
| 'private_transfer'
| 'withdraw'
| 'merge'
/** Roadmap — Confidential DeFi */
| 'defi_adapt'
| 'open_deed'
| 'adjust_deed'
| 'close_deed';
interface ISettlementJourney {
readonly chainId: bigint;
readonly steps: readonly ISettlementStep[];
}
How-tos: deposit · private transfer · withdraw.
Confidential DeFi — SDK V2 journey interfaces
Pool-class Host shells route privacy backends. They do not define Tenebrae’s private DeFi admission model. SDK V2 exposes DeFi as first-class journey steps on the same settlement spine (ADR 0053). Product posture: Operations.
/** Confidential DeFi — sandbox product posture. Venue enablement is per host. */
export interface ITenebraeSdkV2Defi {
/**
* Transient adapt-batch (note → whitelisted multicall → note).
* Examples: Uniswap V3 swap, Aave supply/withdraw — when venue rows enable.
*/
prepareDefiAdapt(args: IPrepareDefiAdaptArgs): Promise<IPreparedSettlement>;
/**
* Position / deed surface (isolated vault account).
* Example family: Aave borrow → repay → close.
*/
prepareOpenPosition(args: IPrepareOpenPositionArgs): Promise<IPreparedSettlement>;
prepareAdjustPosition(args: IPrepareAdjustPositionArgs): Promise<IPreparedSettlement>;
prepareClosePosition(args: IPrepareClosePositionArgs): Promise<IPreparedSettlement>;
}
Admission (protocol intent — not a market claim):
| Gate | Role |
|---|---|
| Selector / target whitelist | Bounds venue blast radius |
boundCallHash in proof | Calldata bound to intent |
| Complete output / conservation | No stranded ERC-20 |
Venue enablement is explicit per venue and per chain.
Embed practices SDK V2 follows
| Practice | SDK V2 home |
|---|---|
Explicit prepare* before sign | prepareDeposit / prepareTransfer / prepareWithdraw |
getPrivateBalance | Private balance view |
| Host-injectable receipt / commitment resolve | Wallet-receipt host port — see embed patterns |
| No custody in embed layer | BYOW — Tenebrae is not a wallet |
Detail: embed patterns.
Wallet Host distribution
Tenebrae SDK V2 is the integrator product whether you embed in your app or ship inside a Kohaku-class Host. Host integrators use the same prepare → prove → submit spine via the Host adapter — not a separate docs lane.
| Surface | Role |
|---|---|
| SDK V2 embed | Your app, automation, or institutional integration |
| Host adapter | Kohaku-class wallet shell — unlock ceremony, plugin verbs, fail-closed defaults |
| Integration Sandbox | /integration/sandbox — bounded dry-run on the docs origin only |
Honesty: Live Host-spend evidence and upstream Kohaku catalog listing are operator-owned. Integration Sandbox is integrator learning — not wallet Host storage and not listing proof.
Integrator decision tree
Need institutional Activity / ops UX?
└─ Yes → Tenebrae client (default for funds)
Need headless / embed settlement in your product or wallet Host?
└─ Yes → Tenebrae SDK V2 (this page)
Need prepare / balance / port literacy?
└─ Read embed patterns — still integrate via SDK V2
Need private Uniswap / Aave today?
└─ Yes — Confidential DeFi in product on sandbox (Product · this page)
For Tenebrae repo contributors
| Topic | Reference |
|---|---|
| Settlement subsystem program | Program 0054 |
| Confidential DeFi program | Program 0053 |
| Wallet-receipt host port spec | WR-016 host API spec |
| Kohaku Host adapter package | packages/kohaku-tenebrae |
| Kohaku extension program hub | Program 0104 |
| Docs / settlement verify posture | Agent navigation |
Claims ceiling for published copy: Stack · Compliance.