dexsession

type Account ¶

type Account [20]byte

Account is a 20-byte EVM account (taker / recipient / owner). Byte-identical to the low 20 bytes of an EVM address; the precompile binds it as the atomic object owner.

type AdminCap ¶

type AdminCap struct {
	// contains filtered or unexported fields
}

AdminCap permits halt/status only, and is granted SEPARATELY (AuthAdmin is not in AuthorityPublic). It cannot withdraw, credit, or override a match.

func (c AdminCap) Authority() Authority

type Authority ¶

type Authority uint32

Authority is a bitmask of the operation classes a capability permits. Each bit maps to exactly one capability type; a bit grants ONLY the read/build/point/ subscribe operations of that class — never a credit.

const (
	AuthQuote      Authority = 1 << 0 // read book/state (Quote, GetState)
	AuthIntent     Authority = 1 << 1 // build a C->D intent + notify (PrepareSwapIntent, NotifyIntent)
	AuthWatch      Authority = 1 << 2 // subscribe to a D result (Poll, OnCommitted)
	AuthSettlement Authority = 1 << 3 // point C at an existing D->C object (ImportSettlement)
	AuthAdmin      Authority = 1 << 4 // halt / status only (separately gated)
)

type CollectRequest ¶

type CollectRequest struct {
	NetworkID      uint32
	CChainID       ID
	DChainID       ID
	Account        Account
	MarketID       ID
	TickLower      int32
	TickUpper      int32
	LiquidityDelta int64 // <0 to remove/collect (a cancel removes the resting amount)
	Salt           ID
	AssetOut       ID // the asset the collect/cancel returns (for correlation)
	CallIndex      uint32
	IsCancel       bool // true => cancel a resting order; false => collect/decrease
}

CollectRequest is the off-chain request to COLLECT/DECREASE (negative-delta) or CANCEL a position/order. Both produce a D->C export (collected fees / withdrawn liquidity / cancelled-order refund) consumed by the ONE DS01 credit path. Cancel is the same shape with the cancel marker; the credit is identical.

type DExportRef ¶

type DExportRef struct {
	SourceChainID ID
	SourceTxID    ID
	OutputIndex   uint32
	IntentID      ID
}

DExportRef points at a D->C atomic export object. It is deliberately NOT a DFillReceipt: it carries no amount the chain trusts and no signature C honours. The chain re-reads the actual object (asset/owner/amount/one-time) on import.

SourceChainID — the D chain whose export the object lives under.
SourceTxID    — the D tx that produced the export.
OutputIndex   — which exported output (deriveUTXOID(SourceTxID, OutputIndex)).
IntentID      — the originating C->D intent (correlation only).

func (r DExportRef) ObjectKey() ID

type DexSession ¶

type DexSession interface {
	// Capability derivation (Cap'n-Proto: you get authority by ASKING the session;
	// it only hands out caps within its bootstrap grant).
	QuoteCap() (QuoteCap, error)
	IntentCap() (IntentCap, error)
	WatchCap() (WatchCap, error)
	SettlementCap() (SettlementCap, error)
	AdminCap() (AdminCap, error)

	// Operations. Each returns a Promise for pipelining; Await for the value.
	Quote(ctx context.Context, req QuoteRequest) *Promise[QuoteResult]
	GetState(ctx context.Context, req StateRequest) *Promise[StateResult]
	PrepareSwapIntent(ctx context.Context, req SwapIntentRequest) *Promise[PreparedIntent]
	NotifyIntent(ctx context.Context, intent *Promise[PreparedIntent]) *Promise[IntentWatch]
	ImportSettlement(ctx context.Context, ref *Promise[DExportRef]) *Promise[SettlementSubmitResult]

	// Grant reports the authority this session was bootstrapped with.
	Grant() Authority
}

DexSession is the RESTRICTED capability a FullServiceNode.Bootstrap returns. It exposes ONLY the orchestration surface — quote/getState/prepareSwapIntent/ notifyIntent/importSettlement — and derives narrowly-scoped capabilities. There is no creditBalance / settleFill / overrideMatch / adminWithdraw: the surface is value-free by construction (see capability.go).

type FlowStages ¶

type FlowStages struct {
	Quote  *Promise[QuoteResult]
	Intent *Promise[PreparedIntent]
	Watch  *Promise[IntentWatch]
	// Committed resolves to the D->C export POINTER when D commits.
	Committed *Promise[DExportRef]
	// Settle resolves to the on-chain settlement calldata/tx (bytes/pointer).
	Settle *Promise[SettlementSubmitResult]
}

FlowStages is the set of promises a SwapFlow produces, exposed so a caller can observe intermediate artifacts (e.g. show the user the estimate, the intent id, the watch) without re-issuing calls. Each is a value/pointer, never authority.

type FullServiceConfig ¶

type FullServiceConfig struct {
	Node  *zaplib.Node
	Venue Venue
	// Markets maps a marketID to its V4 PoolKey args, shared with bootstrapped
	// client sessions so prepareSwapIntent can build calldata. Required for swap
	// preparation; nil => prepare fail-closes for every market.
	Markets func(marketID ID) (PoolKeyArgs, bool)
}

FullServiceConfig configures the server node.

type FullServiceNode ¶

type FullServiceNode struct {
	// contains filtered or unexported fields
}

FullServiceNode wraps a zap.Node and a Venue, exposing Bootstrap. It is the server-side object the spec's `FullServiceNode.bootstrap() -> DexSession` describes.

func NewFullServiceNode(cfg FullServiceConfig) *FullServiceNode

func (fsn *FullServiceNode) Bootstrap(peerID string, grant Authority) DexSession

type ID ¶

type ID [32]byte

ID is a 32-byte identifier (chain id, tx id, market id, intent id, asset id). Byte-identical to luxfi/ids ids.ID and to an EVM bytes32. Native asset == the all-zero ID (mirrors ids.Empty in the dexvm ledger).

func DeriveIntentID(
	networkID uint32,
	cChainID, dChainID ID,
	account Account,
	assetIn ID,
	amountIn uint64,
	marketID ID,
	nonce uint64,
) ID

SHA-256( domain | networkID | cChainID | dChainID |
         account | assetIn | amountIn | marketID | nonce )

func DeriveLiquidityParamsHash(tickLower, tickUpper int32, liquidityDelta int64, salt ID) ID

func DerivePoolKeyHash(pk PoolKeyArgs) ID

func DeriveRoutePathHash(path []ID) ID

func DeriveSessionID(s V4ActionScope) ID

func DeriveSwapParamsHash(zeroForOne bool, amountIn uint64) ID

func DeriveUTXOID(sourceTxID ID, outputIndex uint32) ID

type IntentCap ¶

type IntentCap struct {
	// contains filtered or unexported fields
}

IntentCap permits requesting a C->D intent (build calldata) and notifying D to scan/import the resulting object. It cannot reserve funds, claim a fill, credit, or settle.

func (c IntentCap) Authority() Authority

type IntentPhase ¶

type IntentPhase uint8

IntentPhase is the lifecycle of a notified intent as the off-chain watcher observes it. NONE of these phases moves value — Committed merely means the watcher SAW a D export object; the user still imports it on C.

const (
	PhasePending   IntentPhase = 0 // notified; D has not produced a block yet
	PhaseMatching  IntentPhase = 1 // D imported the C->D object, matching in progress
	PhaseCommitted IntentPhase = 2 // D exported a D->C object (a D block committed)
	PhaseRejected  IntentPhase = 3 // D could not import/match (e.g. unbacked, expired)
	PhaseUnknown   IntentPhase = 4 // watcher has no information
)

type IntentStatus ¶

type IntentStatus struct {
	IntentID   ID
	Phase      IntentPhase
	Ref        DExportRef // valid only when Phase==PhaseCommitted
	Reason     string     // human-readable, for Rejected/Unknown
	MatchedOut uint64     // ESTIMATE (matched output) — orchestration only, never a credit
}

IntentStatus is one poll/push of a watch. When Phase==PhaseCommitted the Ref points at the produced D->C object. A malicious server can set Phase=Committed with a bogus Ref, but importSettlement of that Ref reverts on-chain (the object is missing or binds to a different owner/asset/amount).

MatchedOut is an ESTIMATE the venue reports when D has matched (PhaseMatching/ Committed): the orchestration "you'll receive ~N" figure the bidirectional MatchResult read surfaces. It is INFORMATIONAL ONLY — exactly the QuotedOut discipline extended to the match phase. The chain NEVER trusts it: the credit is the recorded D->C object's amount, bound on-chain at settlement. A lying venue can set MatchedOut to anything; it changes no balance (proven by the RED suite).

type IntentWatch ¶

type IntentWatch struct {
	// contains filtered or unexported fields
}

IntentWatch is the subscription handle a NotifyIntent returns. Poll observes the current phase; OnCommitted yields a Promise that resolves to the DExportRef when (and only when) the watch observes a committed D export.

func (w IntentWatch) IntentID() ID

func (w IntentWatch) OnCommitted(ctx context.Context) *Promise[DExportRef]

func (w IntentWatch) Poll(ctx context.Context) (IntentStatus, error)

type IntentWatchRef ¶

type IntentWatchRef struct {
	IntentID ID
}

IntentWatchRef is the server-side handle a notifyIntent returns: the intent id the watch tracks. The client polls it (MsgWatchPoll) or receives a Push (MsgWatchPush). It is a subscription token, not authority.

type LiquidityRequest ¶

type LiquidityRequest struct {
	NetworkID      uint32
	CChainID       ID
	DChainID       ID
	Account        Account
	MarketID       ID
	TickLower      int32
	TickUpper      int32
	LiquidityDelta int64 // >0 to commit funds
	Salt           ID
	AssetIn        ID
	AmountIn       uint64 // the C-side funding amount locked for the position
	CallIndex      uint32
}

LiquidityRequest is the off-chain request to COMMIT (open/increase) a funded position. LiquidityDelta MUST be positive for a commit (it funds the position from C); the negative-delta (collect/decrease/cancel) path is V4CollectSession / openCancel, whose credit rides the DS01 settlement.

type ModifyLiquidityArgs ¶

type ModifyLiquidityArgs struct {
	TickLower      int32 // int24
	TickUpper      int32 // int24
	LiquidityDelta int64 // int256 (we carry the int64 magnitude+sign; ABI sign-extends)
	Salt           ID    // bytes32 position salt
}

ModifyLiquidityArgs are the V4 ModifyLiquidityParams tuple fields. LiquidityDelta is signed: >0 add, <0 remove. The session sets the sign per action (commit vs collect/cancel); the SIGN is what distinguishes a funding C->D commit from a value-returning D->C removal — both ride this one selector, exactly as the position facade does.

type PoolKeyArgs ¶

type PoolKeyArgs struct {
	Currency0   Account
	Currency1   Account
	Fee         uint32 // uint24
	TickSpacing int32  // int24
	Hooks       Account
}

PoolKeyArgs are the V4 PoolKey tuple fields the swap selector takes: (currency0, currency1, fee uint24, tickSpacing int24, hooks address). For the native seam the pool is identified by these; the keeper/market binds them to a D market. dexsession fills them from the request's market mapping.

type PreparedIntent ¶

type PreparedIntent struct {
	To        Account // 0x9999
	Calldata  []byte  // selector + args (the user signs a tx with this data)
	HookData  []byte  // V4 hookData consumed by the 0x9999 handler
	IntentID  ID      // deterministic id the signed tx will create on C
	QuotedOut uint64  // estimate only
	// Echoed request identity so the watch / import can reconstruct the binding
	// without holding the whole request.
	DChainID  ID
	CChainID  ID
	Account   Account
	Recipient Account
	AssetIn   ID
	AmountIn  uint64
	MarketID  ID
}

PreparedIntent is the OUTPUT of prepareSwapIntent: everything the user needs to sign a normal C tx to 0x9999 that creates the funded C->D intent. It is bytes, not authority:

• To — the 0x9999 settlement address (the precompile).
• Calldata — selector + ABI-encoded args for the on-chain swap entry.
• HookData — the V4 hookData the 0x9999 handler consumes (routing payload).
• IntentID — the deterministic id the on-chain SubmitSwapIntent will mint (derived identically here; lets the watch locate the D result).
• QuotedOut — the ESTIMATE used to build it (informational, not enforceable).

MUST NOT: reserve funds off-chain, claim a fill final, return an amountOut the chain trusts. The QuotedOut is explicitly informational; the enforceable floor is MinAmountOut baked into Calldata, which the chain/D check.

type Promise ¶

type Promise[T any] struct {
	// contains filtered or unexported fields
}

Promise is a future for an async DexSession call result of type T. It is safe for one producer (the dispatching goroutine) and many consumers (Await is idempotent and concurrent-safe).

func (p *Promise[T]) Await(ctx context.Context) (T, error)

type QuoteCap ¶

type QuoteCap struct {
	// contains filtered or unexported fields
}

QuoteCap permits read-only book/state queries. It can quote and observe; it cannot build an intent, notify, settle, or administer.

func (c QuoteCap) Authority() Authority

type QuoteRequest ¶

type QuoteRequest struct {
	MarketID   ID
	AmountIn   uint64
	ZeroForOne bool // sell currency0 for currency1
}

QuoteRequest asks the D book for an estimated output. Read-only.

type QuoteResult ¶

type QuoteResult struct {
	MarketID    ID
	AmountIn    uint64
	AmountOut   uint64 // ESTIMATE ONLY — not enforceable, not a credit
	BestPricePx uint64 // top-of-book price, IEEE-754 bits (informational)
	Liquid      bool   // false = no resting book / market unknown
}

QuoteResult is an ESTIMATE. AmountOut is informational only: the chain never trusts it. The user still encodes their own MinAmountOut in the signed C tx, and D enforces slippage at match. A stale or malicious quote can only mislead a UI — it cannot move value, and a bad quote that misses MinAmountOut makes the on-chain swap revert (TestZAP_StaleResponse_BadQuoteMissesMinOutOrReverts).

type RoutePhase ¶

type RoutePhase uint8

RoutePhase is the lifecycle of a route as the off-chain watcher observes it. Like IntentPhase, NONE of these moves value; Committed means the watcher saw the ONE final D->C export, Refunded means it saw the ONE refund export.

const (
	RoutePending   RoutePhase = 0 // notified; D has not started the route
	RouteHopping   RoutePhase = 1 // D is walking the path (a hop is in progress)
	RouteCommitted RoutePhase = 2 // D produced the ONE final D->C export
	RouteRefunded  RoutePhase = 3 // route failed; D produced the ONE refund export
	RouteRejected  RoutePhase = 4 // D could not import/route (e.g. unbacked, expired)
	RouteUnknown   RoutePhase = 5
)

type RouteRequest ¶

type RouteRequest struct {
	NetworkID    uint32
	CChainID     ID
	DChainID     ID
	Account      Account // taker — bound as the single C->D input object owner
	AssetIn      ID      // the input asset locked on C (hop 0 input)
	AssetInAddr  Account // ERC-20 token (zero for native) for the C lock
	AmountIn     uint64  // the SINGLE input amount
	Path         []ID    // ordered marketIDs the route walks: A->B->C
	MinAmountOut uint64  // floor on the FINAL output asset (D-enforced)
	Recipient    Account // where the FINAL D->C export must credit
	Deadline     uint64
	CallIndex    uint32
}

RouteRequest is the off-chain request to PREPARE a multi-hop route intent. Like a SwapIntentRequest it reserves no funds and returns calldata; the difference is Path — the ordered list of marketIDs D walks (A->B->C). AmountIn is the SINGLE input the user locks on C; MinAmountOut is the floor on the FINAL output, enforced by D at the end of the route (a route that cannot deliver MinAmountOut of the final asset refunds the input — it never partially settles an intermediate asset).

type RouteStatus ¶

type RouteStatus struct {
	IntentID     ID
	Phase        RoutePhase
	HopIndex     uint32     // the current/last hop the router reached (0-based)
	HopCount     uint32     // total hops in the path
	HopAmountOut uint64     // ESTIMATE: output of the current hop (orchestration only)
	FinalOut     uint64     // ESTIMATE: final output (orchestration only)
	Ref          DExportRef // the ONE final (or refund) export; valid at Committed/Refunded
	Reason       string
}

RouteStatus is one poll/push of a route watch. HopIndex/HopAmountOut describe the CURRENT hop (orchestration ESTIMATES). Ref is the FINAL export POINTER, valid only when Phase==RouteCommitted (the final output) or RouteRefunded (the refund). There is no per-hop Ref field — by construction there is no per-hop settleable object.

type RouteVenue ¶

type RouteVenue interface {
	// NotifyRoute tells the venue to scan the SINGLE C->D input object the user's
	// signed tx created and begin walking the path carried in the request. It returns
	// the deterministic route intent id to watch; it does NOT build calldata (the
	// SESSION builds calldata client-side from the user's own path, so a malicious
	// server cannot inject a forged path the user would sign), does not block on a D
	// block, and credits nothing.
	NotifyRoute(req RouteRequest) (IntentWatchRef, error)

	// RouteStatus reports the current route phase + hop progress, and (when D has
	// committed) the POINTER to the ONE final (or refund) export. It reads D/shared-
	// memory state; it never fabricates a credit.
	RouteStatus(intentID ID) (RouteStatus, error)
}

RouteVenue is the route backend a Venue MAY ALSO implement. It is a SEPARATE interface (composition, not interface-expansion) so the base Venue — and every existing implementation — stays unchanged: a server type-asserts for RouteVenue and serves routes only when the backend provides it. Like Venue, it has NO credit/settle method: it reports route progress and the final export POINTER; it never moves value. Exactly TWO methods — one trigger, one status — keeps it DRY.

type RouteWatch ¶

type RouteWatch struct {
	// contains filtered or unexported fields
}

RouteWatch is the subscription a route NotifyCToDExport returns. Poll observes the current route phase + hop progress; streamUntilFinal resolves the ONE final (or refund) export pointer. It NEVER moves value — the terminal pointer feeds the one DS01 settlement, which the chain judges.

func (w RouteWatch) IntentID() ID

func (w RouteWatch) Poll(ctx context.Context) (RouteStatus, error)

type SessionConfig ¶

type SessionConfig struct {
	Conn    caller
	PeerID  string
	Grant   Authority
	Markets func(marketID ID) (PoolKeyArgs, bool)
}

SessionConfig configures a client session (normally produced by Bootstrap, but exported so a node can construct one directly against a known peer).

type SettlementCap ¶

type SettlementCap struct {
	// contains filtered or unexported fields
}

SettlementCap permits asking C to import an EXISTING D->C object (build the finalization calldata / submit a pointing tx). It cannot credit C through RPC, nor substitute recipient/asset/amount — the chain binds those to the object.

func (c SettlementCap) Authority() Authority

type SettlementMode ¶

type SettlementMode uint8

SettlementMode tells the caller HOW the settlement is realised. In both modes the credit happens ON-CHAIN by consuming the real object — never via this RPC.

const (
	// SettleCalldata: the caller (a wallet / keeper) signs a C tx to 0x9999 with
	// the returned Calldata. The chain's ImportSettlement reads the real D->C
	// object and credits the recipient.
	SettleCalldata SettlementMode = 0
	// SettleSubmitted: a keeper with a (non-custodial) signing key already
	// submitted the C tx; CTxHash is the submitted tx. The keeper cannot alter
	// recipient/asset/amount — the chain binds them to the object.
	SettleSubmitted SettlementMode = 1
)

type SettlementSubmitResult ¶

type SettlementSubmitResult struct {
	Mode      SettlementMode
	To        Account // 0x9999
	Calldata  []byte  // selector + SettlementClaim args, points at the object
	ObjectKey ID      // the shared-memory key the chain will read
	CTxHash   ID      // set only in SettleSubmitted mode
}

SettlementSubmitResult is the OUTPUT of importSettlement. It NEVER credits C; it returns the calldata to consume the object (or the hash of a tx that points at it). The on-chain ImportSettlement is the sole credit path.

type StateKind ¶

type StateKind uint8

StateKind selects which read-only view getState returns.

const (
	StateMarket  StateKind = 0 // market existence / base+quote asset ids
	StateBalance StateKind = 1 // an account's D available balance for an asset
	StateIntent  StateKind = 2 // a C->D intent's known routing status (off-chain view)
)

type StateRequest ¶

type StateRequest struct {
	Kind     StateKind
	MarketID ID
	Account  Account
	Asset    ID
	IntentID ID
}

StateRequest is a read-only DEX state query.

type StateResult ¶

type StateResult struct {
	Kind      StateKind
	Exists    bool
	BaseID    ID
	QuoteID   ID
	Available uint64 // D available balance (observation only)
	Known     bool   // intent known to the venue's router index
}

StateResult is the read-only answer. Like a quote it is informational: a balance reported here is NOT a spendable claim the chain honours — only a consumed D->C object credits C.

type SwapIntentRequest ¶

type SwapIntentRequest struct {
	NetworkID    uint32
	CChainID     ID
	DChainID     ID
	Account      Account // taker — bound as the C->D object owner on-chain
	AssetIn      ID      // full injective asset id locked on C
	AssetInAddr  Account // ERC-20 token (zero for native) for the C lock
	AmountIn     uint64
	MarketID     ID
	MinAmountOut uint64  // taker slippage floor — encoded into the signed tx
	Recipient    Account // where the D->C settlement must credit
	Deadline     uint64
	// Nonce is the taker's intent disambiguator, carried in the swap's DI01 hookData and
	// folded into DeriveIntentID. It makes the intent id CHAIN-OBSERVABLE — the off-chain
	// prepare derives the SAME id the on-chain SubmitSwapIntent mints (the watch then
	// correlates against the live chain), and it distinguishes two otherwise-identical
	// swaps. The user's wallet sets it (a per-account order nonce); 0 for a single swap.
	// It REPLACES the former CallIndex (which depended on the unknown-pre-signing txID
	// ordering and so could not be reproduced off-chain).
	Nonce uint64
}

SwapIntentRequest is the off-chain request to PREPARE a C->D swap intent. The session validates params, estimates a quote, derives the intent id, and returns a PreparedIntent (calldata). It reserves NO funds and returns NO enforceable amountOut.

type V4Action ¶

type V4Action uint8

V4Action is the kind of V4 action a session capability is scoped to. A scoped capability is confined to exactly one kind — a swap cap cannot drive a liquidity action and vice versa.

const (
	ActionSwap V4Action = iota
	ActionRoute
	ActionModifyLiquidity
	ActionCollect
	ActionCancel
	ActionState
)

func (a V4Action) String() string

type V4ActionScope ¶

type V4ActionScope struct {
	NetworkID   uint32
	CChainID    ID
	DChainID    ID
	Addr9999    Account
	Account     Account
	PoolKeyHash ID
	ParamsHash  ID
	Kind        V4Action
	IntentID    ID
}

V4ActionScope binds a session capability to ONE V4 action. Every field that distinguishes one action from another is here; DeriveSessionID hashes them into a stable id. Two sessions for different intents/pools/params/kinds derive different ids and their capabilities cannot be cross-used.

NetworkID    — the Lux network the action runs on.
CChainID     — the C-Chain (EVM balance authority).
DChainID     — the D-Chain (matching authority).
Addr9999     — the on-chain settlement authority (the precompile address).
Account      — the caller / account the action is for (bound as the object owner).
PoolKeyHash  — hash of the V4 PoolKey (which market). For a route, hash of the
               whole path (see DeriveRoutePathHash).
ParamsHash   — hash of the action params (direction+amount for a swap; tick range
               +delta for liquidity; the collected/cancelled selector for those).
Kind         — the V4Action this scope permits.
IntentID     — the deterministic intent id (for swap/route) the action targets.
               Zero for actions whose object is not an intent (a position commit
               binds by PoolKeyHash+ParamsHash+Account instead).

type V4CollectSession ¶

type V4CollectSession struct {
	// contains filtered or unexported fields
}

V4CollectSession is the removal lifecycle (collect/decrease/cancel). It requests the removal, watches for the ONE D->C export, and settles it via the DS01 credit path.

func (s *V4CollectSession) Close()

func (s *V4CollectSession) IntentID() ID

func (s *V4CollectSession) OnExportReady(ctx context.Context, watch IntentWatch) *Promise[DExportRef]

func (s *V4CollectSession) SessionID() ID

func (s *V4CollectSession) WriteNotify(ctx context.Context, intent *Promise[PreparedIntent]) *Promise[IntentWatch]

func (s *V4CollectSession) WritePrepareCSettlement(ctx context.Context, ref *Promise[DExportRef]) *Promise[SettlementSubmitResult]

func (s *V4CollectSession) WriteRequest(ctx context.Context) *Promise[PreparedIntent]

type V4Config ¶

type V4Config struct {
	Session   DexSession
	NetworkID uint32
	CChainID  ID
	DChainID  ID
	// Addr9999 is the on-chain settlement authority. Defaults to the canonical
	// 0x...9999 if zero.
	Addr9999 Account
}

V4Config configures the V4 precompile session. The chain identifiers and the 0x9999 address are fixed for the deployment; they bind every action's scope.

type V4Dir ¶

type V4Dir uint8

V4Dir classifies a message by who originates it on the bidirectional plane.

const (
	// DirCToD is a C-side -> D-side WRITE (request side of a Call, or the user's
	// signed C tx the write refers to). It may trigger D work; it never moves value.
	DirCToD V4Dir = iota
	// DirDToC is a D-side -> C-side READ (response side of a Call, or a watch
	// push/poll). It carries estimates / status / a POINTER; never a credit.
	DirDToC
	// DirLocal is a client-side lifecycle transition (open/close): it mints/retires a
	// scoped capability and session state. It touches no peer and no value.
	DirLocal
)

type V4Event ¶

type V4Event struct {
	Type      V4MsgType
	SessionID ID
	IntentID  ID
	EstAmount uint64
	HopIndex  uint32
	Ref       DExportRef
	Reason    string
}

V4Event is the typed D->C read a session surfaces to the caller (the orchestration stream). It is a VALUE: a label + the orchestration payload + an OPTIONAL pointer. It NEVER carries authority over a balance:

• Type — the V4MsgType (always a DirDToC read).
• SessionID — the action the event belongs to (binds it to its session).
• IntentID — the originating intent (correlation).
• EstAmount — an ESTIMATE (quote / matched-out / hop-out). NOT a credit; the chain never trusts it. Exactly the QuotedOut discipline, extended to matches.
• HopIndex — the route hop this event describes (route events only).
• Ref — the D->C export POINTER, set ONLY on *_EXPORT_READY / REFUND_READY. The credit still happens on-chain when the real object behind Ref is consumed.
• Reason — human text for ERROR / HALTED / REFUND.

func (e V4Event) HasRef() bool

type V4LiquiditySession ¶

type V4LiquiditySession struct {
	// contains filtered or unexported fields
}

V4LiquiditySession is the position-commit lifecycle. It builds modifyLiquidity (+delta) calldata the user signs to fund the position, notifies D, and observes the position opening. It has NO settlement method (a commit credits nothing).

func (s *V4LiquiditySession) Close()

func (s *V4LiquiditySession) IntentID() ID

func (s *V4LiquiditySession) SessionID() ID

func (s *V4LiquiditySession) WriteNotifyCToDExport(ctx context.Context, intent *Promise[PreparedIntent]) *Promise[IntentWatch]

func (s *V4LiquiditySession) WritePrepareCommit(ctx context.Context) *Promise[PreparedIntent]

type V4MsgType ¶

type V4MsgType uint16

V4MsgType is a control-plane message-type. The constants below are the V4-native SEMANTIC names the spec mandates. Each maps to an underlying wire frame (Msg* in wire.go) or to a LOCAL lifecycle transition (no wire frame — e.g. *_OPEN mints a scoped capability client-side). A session is a state machine that emits/consumes these; the mapping (v4Wire) keeps the wire the single source of transport truth.

const (
	V4_SWAP_OPEN V4MsgType = 0x1000 + iota
	V4_SWAP_PREPARE_INTENT
	V4_SWAP_NOTIFY_C_EXPORT
	V4_SWAP_D_IMPORTED
	V4_SWAP_MATCHED
	V4_SWAP_D_EXPORT_READY
	V4_SWAP_PREPARE_C_SETTLEMENT
	V4_SWAP_SUBMIT_C_SETTLEMENT
	V4_SWAP_C_SETTLED
)

OPEN [local]
  -> PREPARE_INTENT     [C->D] build 0x9999 swap calldata (DI01) the user signs
  -> NOTIFY_C_EXPORT    [C->D] tell D to scan the C->D object the signed tx made
  <- D_IMPORTED         [D->C] D imported the C->D object (Phase Matching)
  <- MATCHED            [D->C] D matched (MatchResult.amountOut = ESTIMATE only)
  <- D_EXPORT_READY     [D->C] D committed a D->C export (DExportRef POINTER)
  -> PREPARE_C_SETTLEMENT [C->D] build 0x9999 settlement calldata (DS01) at the ref
  -> SUBMIT_C_SETTLEMENT  [C->D] (optional) a keeper submits the signed C tx
  <- C_SETTLED          [D->C] C consumed the real object and credited (observed)

const (
	V4_ROUTE_OPEN V4MsgType = 0x1100 + iota
	V4_ROUTE_PREPARE_INTENT
	V4_ROUTE_NOTIFY_C_EXPORT
	V4_ROUTE_HOP_STARTED
	V4_ROUTE_HOP_FILLED
	V4_ROUTE_D_EXPORT_READY
	V4_ROUTE_REFUND_READY
	V4_ROUTE_PREPARE_C_SETTLEMENT
	V4_ROUTE_C_SETTLED
)

OPEN [local]
  -> PREPARE_INTENT     [C->D] ONE route-intent calldata (DI01 + path body)
  -> NOTIFY_C_EXPORT    [C->D] tell D to scan the single C->D input object
  <- HOP_STARTED        [D->C] D began hop i (orchestration — no C object)
  <- HOP_FILLED         [D->C] D filled hop i (intermediate amount — orchestration)
  <- D_EXPORT_READY     [D->C] D committed the ONE final D->C export (POINTER)
  <- REFUND_READY       [D->C] route failed: D exported a refund of the INPUT asset
  -> PREPARE_C_SETTLEMENT [C->D] settle the ONE final (or refund) export (DS01)
  <- C_SETTLED          [D->C] C credited from the single real object (observed)

const (
	V4_LP_OPEN V4MsgType = 0x1200 + iota
	V4_LP_PREPARE_COMMIT
	V4_LP_NOTIFY_C_EXPORT
	V4_LP_D_COMMITTED
	V4_LP_POSITION_OPEN
)

OPEN [local]
  -> PREPARE_COMMIT     [C->D] build 0x9999 modifyLiquidity calldata (+delta)
  -> NOTIFY_C_EXPORT    [C->D] tell D to scan the funded C->D position object
  <- D_COMMITTED        [D->C] D recorded the position (orchestration)
  <- POSITION_OPEN      [D->C] the position id is live (orchestration)

const (
	V4_COLLECT_OPEN V4MsgType = 0x1300 + iota
	V4_COLLECT_REQUEST
	V4_COLLECT_D_EXPORT_READY
	V4_COLLECT_PREPARE_C_SETTLEMENT
	V4_COLLECT_C_SETTLED
)

OPEN [local]
  -> REQUEST            [C->D] ask D to collect/decrease (build -delta calldata)
  <- D_EXPORT_READY     [D->C] D committed the D->C export of the collected value
  -> PREPARE_C_SETTLEMENT [C->D] settle the export (DS01) -> credit
  <- C_SETTLED          [D->C] C credited from the real object (observed)

const (
	V4_CANCEL_OPEN V4MsgType = 0x1400 + iota
	V4_CANCEL_REQUEST
	V4_CANCEL_D_EXPORT_READY
	V4_CANCEL_PREPARE_C_SETTLEMENT
	V4_CANCEL_C_SETTLED
)

const (
	V4_STATE_OPEN V4MsgType = 0x1500 + iota
	V4_STATE_QUOTE_UPDATE
	V4_STATE_BOOK_UPDATE
	V4_STATE_CLOSE
)

const (
	// V4_ERROR is a D->C error read (the venue reports a non-fatal failure for this
	// action). It carries a reason; it never moves value.
	V4_ERROR V4MsgType = 0x1F00 + iota
	// V4_HALTED is a D->C read that the action's market/asset/global swap path is
	// halted. The session refuses to advance (fail-secure). It moves no value (a halt
	// blocks NEW swaps; funds still exit via the un-halted settlement path on-chain).
	V4_HALTED
)

func (t V4MsgType) CreditsValue() bool

func (t V4MsgType) Dir() V4Dir

func (t V4MsgType) String() string

type V4PrecompileSession ¶

type V4PrecompileSession struct {
	// contains filtered or unexported fields
}

V4PrecompileSession is the per-action session factory the spec mandates. It wraps a restricted DexSession (the bootstrap grant) and opens a NARROWLY-SCOPED session per V4 action. Each open* mints a scopedCap confined to {networkID, cChainID, dChainID, 0x9999, account, poolKeyHash, paramsHash, intentID} for exactly that action, so a session cannot drive any other intent/pool/params/kind.

func NewV4PrecompileSession(cfg V4Config) (*V4PrecompileSession, error)

func (v *V4PrecompileSession) OpenCancel(req CollectRequest) (*V4CollectSession, error)

func (v *V4PrecompileSession) OpenCollect(req CollectRequest) (*V4CollectSession, error)

func (v *V4PrecompileSession) OpenModifyLiquidity(req LiquidityRequest) (*V4LiquiditySession, error)

func (v *V4PrecompileSession) OpenRoute(req RouteRequest) (*V4RouteSession, error)

func (v *V4PrecompileSession) OpenState(account Account, marketID ID) (*V4StateSession, error)

func (v *V4PrecompileSession) OpenSwap(req SwapIntentRequest) (*V4SwapSession, error)

type V4RouteSession ¶

type V4RouteSession struct {
	// contains filtered or unexported fields
}

V4RouteSession is the multi-hop route lifecycle state machine. It prepares EXACTLY ONE C->D input intent (carrying the path), streams hop progress as orchestration, and settles the ONE final D->C export. It NEVER produces an intermediate-asset settlement.

func (s *V4RouteSession) Close()

func (s *V4RouteSession) IntentID() ID

func (s *V4RouteSession) OnFinalExport(ctx context.Context, watch RouteWatch) *Promise[DExportRef]

func (s *V4RouteSession) Path() []ID

func (s *V4RouteSession) ReadStream(ctx context.Context, watch RouteWatch) <-chan V4Event

func (s *V4RouteSession) SessionID() ID

func (s *V4RouteSession) WriteNotifyCToDExport(ctx context.Context, intent *Promise[PreparedIntent]) *Promise[RouteWatch]

func (s *V4RouteSession) WritePrepareCSettlement(ctx context.Context, ref *Promise[DExportRef]) *Promise[SettlementSubmitResult]

func (s *V4RouteSession) WritePrepareIntent(ctx context.Context) *Promise[PreparedIntent]

type V4StateSession ¶

type V4StateSession struct {
	// contains filtered or unexported fields
}

V4StateSession is the read-only streaming session: quotes and book/state. It cannot build calldata, notify, or settle — it observes.

func (s *V4StateSession) Close()

func (s *V4StateSession) ReadQuote(ctx context.Context, amountIn uint64, zeroForOne bool) *Promise[QuoteResult]

func (s *V4StateSession) ReadState(ctx context.Context, kind StateKind, account Account, asset ID) *Promise[StateResult]

func (s *V4StateSession) SessionID() ID

func (s *V4StateSession) StreamQuotes(ctx context.Context, amountIn uint64, zeroForOne bool) <-chan V4Event

type V4SwapSession ¶

type V4SwapSession struct {
	// contains filtered or unexported fields
}

V4SwapSession is the single-swap lifecycle state machine. It exposes the bidirectional message set as typed methods that compose the clientSession ops and pipeline via Promise. It holds a scopedCap confined to ONE swap.

func (s *V4SwapSession) Close()

func (s *V4SwapSession) IntentID() ID

func (s *V4SwapSession) OnExportReady(ctx context.Context, watch IntentWatch) *Promise[DExportRef]

func (s *V4SwapSession) ReadStream(ctx context.Context, watch IntentWatch) <-chan V4Event

func (s *V4SwapSession) Run(ctx context.Context) FlowStages

func (s *V4SwapSession) SessionID() ID

func (s *V4SwapSession) WriteNotifyCToDExport(ctx context.Context, intent *Promise[PreparedIntent]) *Promise[IntentWatch]

func (s *V4SwapSession) WritePrepareCSettlement(ctx context.Context, ref *Promise[DExportRef]) *Promise[SettlementSubmitResult]

func (s *V4SwapSession) WritePrepareIntent(ctx context.Context) *Promise[PreparedIntent]

type Venue ¶

type Venue interface {
	// Quote returns an ESTIMATE from the resting book. Read-only.
	Quote(ctx context.Context, req QuoteRequest) (QuoteResult, error)

	// State returns a read-only C/D DEX observation.
	State(ctx context.Context, req StateRequest) (StateResult, error)

	// NotifyIntent asks the venue to begin scanning shared memory for the C->D
	// object named by the intent and submit a D tx that imports+matches it under
	// dexvm consensus. It returns immediately with the intent id to watch; it does
	// NOT block on a D block and does NOT credit anything. A no-op-but-record
	// implementation is valid (the keeper picks up the on-chain IntentSubmitted
	// event); the watch then observes the export when D commits.
	NotifyIntent(ctx context.Context, intent PreparedIntent) (IntentWatchRef, error)

	// WatchStatus reports the current phase of a notified intent and, when D has
	// committed an export, the POINTER to it. It reads D/shared-memory state; it
	// never fabricates a credit. Returning PhaseCommitted with a ref is a CLAIM the
	// chain re-verifies on import.
	WatchStatus(ctx context.Context, intentID ID) (IntentStatus, error)

	// ResolveExport maps a DExportRef to the on-chain settlement calldata that
	// points at the real D->C object. It does NOT submit and does NOT credit; it
	// returns the bytes a wallet/keeper signs. The asset+recipient are NOT taken
	// from the ref (the chain derives the asset from swap direction and binds the
	// recipient to the caller); the calldata carries only outputID + amount, and
	// even those are bound on-chain. amount is the venue's best knowledge of the
	// export amount, used to populate the claim; a wrong amount makes the on-chain
	// bind revert (it must equal the recorded object's amount).
	ResolveExport(ctx context.Context, ref DExportRef) (SettlementSubmitResult, error)
}

Venue is the read + trigger backend a DexSession server delegates to. It is the D-Chain CLOB venue and a C/D state reader. CRITICALLY, it has no credit/settle method: the orchestration server cannot move value because its backend cannot either. (A real deployment backs Venue with the lux/dex ZAP CLOB client over the existing clob_* transport for quotes, plus a chain-state reader for exports.)

type WatchCap ¶

type WatchCap struct {
	// contains filtered or unexported fields
}

WatchCap permits subscribing to a notified intent's D result. It cannot move value; OnCommitted yields a POINTER (DExportRef), not a credit.

func (c WatchCap) Authority() Authority