Documentation
¶
Overview ¶
Package txs defines transaction types for the DEX VM — a STATELESS ATOMIC ZAP PROXY. There is NO local matching, NO AMM, NO embedded order book. The transaction surface is exactly the two concerns a proxy owns:
ATOMIC VALUE MOVEMENT (C-Chain <-> proxy), modeled on the platformvm Import/Export txs that move value between primary-network chains in a single atomic shared-memory commit: - TxImport : claim value exported from C-Chain into the proxy. - TxExport : settle proceeds (and unfilled IOC remainder) back to C-Chain, derived ONLY from confirmed d-chain fills.
ORDER RELAY (proxy -> d-chain over ZAP), transport only: - TxRelayOrder : an opaque, byte-identical clob_* ZAP payload plus a reference to the collateral already locked by an Import. The matcher is the d-chain; the proxy never matches. - TxPlaceOrder / TxCancelOrder : thin relay envelopes (a CLOB place / cancel forwarded verbatim). They carry NO price/size matching semantics in the proxy — the d-chain is the single source of truth.
Index ¶
Constants ¶
This section is empty.
Variables ¶
Functions ¶
Types ¶
type AtomicInput ¶ added in v1.3.8
type AtomicInput struct {
UTXOID ids.ID `json:"utxoId"`
Asset ids.ID `json:"asset"`
Amount uint64 `json:"amount"`
}
AtomicInput references a UTXO exported from the source chain that an Import consumes via shared memory. UTXOID is the source-chain UTXO id (the InputID()); Asset and Amount describe the value being claimed.
type AtomicOutput ¶ added in v1.3.8
type AtomicOutput struct {
Rail Rail `json:"rail,omitempty"`
Owner ids.ShortID `json:"owner"`
Asset ids.ID `json:"asset"`
Amount uint64 `json:"amount"`
}
AtomicOutput is a value output: an Import credits these locally; an Export puts these into shared memory for the destination chain to claim. Rail is the lane the value travels (RailSwap default / RailLP), bound byte-for-byte into the shared-memory object so the precompile's matching consume path is the only one that can claim it.
type BaseTx ¶
type BaseTx struct {
TxID ids.ID `json:"-"`
TxType TxType `json:"type"`
From ids.ShortID `json:"from"`
Nonce uint64 `json:"nonce"`
GasPrice uint64 `json:"gasPrice"`
GasLimit uint64 `json:"gasLimit"`
CreatedAt int64 `json:"createdAt"`
Signature []byte `json:"signature"`
// contains filtered or unexported fields
}
BaseTx contains common fields for all transactions.
TxID is intentionally NOT serialized (json:"-"): the transaction ID is the SHA-256 checksum of the wire bytes, so embedding it in those same bytes would be circular and would make the ID depend on whatever value happened to be in the field at marshal time. It is always (re)derived from the wire on Parse, and stamped by finalize on construction.
type CancelOrderTx ¶
type CancelOrderTx struct {
BaseTx
PoolID [32]byte `json:"poolId"`
OrderID uint64 `json:"orderId"`
}
CancelOrderTx is a thin relay envelope for a CLOB cancel. The d-chain authenticates the cancel against the resting order's maker — the proxy only forwards the (market, orderID) reference.
func NewCancelOrderTx ¶
func NewCancelOrderTx(from ids.ShortID, nonce uint64, poolID [32]byte, orderID uint64) *CancelOrderTx
NewCancelOrderTx creates a new cancel-order relay envelope.
func (*CancelOrderTx) Verify ¶
func (tx *CancelOrderTx) Verify() error
type ExportTx ¶ added in v1.3.8
type ExportTx struct {
BaseTx
DestinationChain ids.ID `json:"destinationChain"`
ExportedOutputs []AtomicOutput `json:"exportedOutputs"`
// FillRef binds this settlement to the d-chain relay receipt whose confirmed
// fills justify the exported amounts (replay-idempotency / audit).
FillRef ids.ID `json:"fillRef"`
}
ExportTx settles proceeds back to C-Chain (the DestinationChain). The atomic shared-memory export leg: ExportedOutputs are written into shared memory for the destination chain to claim. The amounts MUST be derived ONLY from confirmed d-chain fills (and any unfilled IOC remainder being refunded) — the proxy never mints. This is the FINAL leg of the conservation ordering.
func NewExportTx ¶ added in v1.3.8
func NewExportTx(from ids.ShortID, nonce uint64, destChain ids.ID, out []AtomicOutput, fillRef ids.ID) *ExportTx
NewExportTx creates a new export transaction.
func NewSettlementExportTx ¶ added in v1.3.8
func NewSettlementExportTx(from ids.ShortID, txIndex uint32, destChain ids.ID, out []AtomicOutput, fillRef ids.ID, createdAt int64) *ExportTx
NewSettlementExportTx builds the settlement export the VM constructs INSIDE block processing (settleFromFills) — never a client-submitted tx. Because it is reconstructed independently on every validator, its identity must be a pure function of consensus-agreed inputs only. The wall-clock CreatedAt used by the client-facing NewExportTx would make tx.ID() (and therefore any shared-memory UTXO key derived from it) diverge per node, splitting the atomic commit. Here CreatedAt is pinned to createdAt — the deterministic settlement coordinate (the relay's UnixNano block time) supplied by the caller — so the wire bytes, the TxID, and every derived export UTXO key are byte-identical across validators. Nonce carries the settlement's txIndex so two settlements in the same block produce distinct identities.
type ImportTx ¶ added in v1.3.8
type ImportTx struct {
BaseTx
SourceChain ids.ID `json:"sourceChain"`
ImportedInputs []AtomicInput `json:"importedInputs"`
Outputs []AtomicOutput `json:"outputs"`
}
ImportTx claims value exported from C-Chain (the SourceChain) into the proxy. The atomic shared-memory import leg: the imported UTXOs are removed from shared memory and their value credited to local outputs. This is the FIRST leg of the conservation ordering (import -> ZAP submit -> export).
func NewImportTx ¶ added in v1.3.8
func NewImportTx(from ids.ShortID, nonce uint64, sourceChain ids.ID, in []AtomicInput, out []AtomicOutput) *ImportTx
NewImportTx creates a new import transaction.
type PlaceOrderTx ¶
type PlaceOrderTx struct {
BaseTx
// PoolID is the 32-byte market identity (V4 poolId) the d-chain keys by.
PoolID [32]byte `json:"poolId"`
Side uint8 `json:"side"` // 0 = Buy/bid, 1 = Sell/ask
Price uint64 `json:"price"`
Size uint64 `json:"size"`
// CollateralRef references the Import whose locked value backs this order.
CollateralRef ids.ID `json:"collateralRef"`
}
PlaceOrderTx is a thin relay envelope for a CLOB limit-order placement. It carries the wire fields a clob_place frame needs but NO matching logic — the VM forwards it to the d-chain and settles from the returned ack/fills.
func NewPlaceOrderTx ¶
func NewPlaceOrderTx(from ids.ShortID, nonce uint64, poolID [32]byte, side uint8, price, size uint64) *PlaceOrderTx
NewPlaceOrderTx creates a new place-order relay envelope.
func (*PlaceOrderTx) Verify ¶
func (tx *PlaceOrderTx) Verify() error
type Rail ¶ added in v1.3.14
type Rail uint8
Rail is the cross-chain object's lane discriminator — the FIRST wire byte of the shared-memory object (atomic.go encodeExportedOutput). It is the H1-closing tag the precompile (precompile/dex/native_wire.go Rail) binds on the C side: a swap-fill object is RailSwap, an LP-collect object is RailLP, and each C-side consume path accepts ONLY its own rail (so a cross-rail consume can never reach the wrong pot). The proxy stamps it on every exported output and binds it on every import, so the rail round-trips through the atomic core unchanged.
const ( // RailSwap is the swap-fill / refund lane — the ZERO value, so an output whose rail // is unstated (the proxy's settleFromFills fill/refund exports, every legacy // custody/conservation path) defaults to the swap rail. The precompile's // ImportSettlement consumes ONLY this rail. RailSwap Rail = 0 // RailLP is the LP position-commit / collect lane — a non-zero tag the proxy's // executeWithdraw stamps for an LP collect/withdraw. The precompile's // ImportPositionCollect consumes ONLY this rail. RailLP Rail = 1 )
type RelayOrderTx ¶ added in v1.3.8
type RelayOrderTx struct {
BaseTx
// Method is the ZAP CLOB method ("clob_submit", "clob_place", "clob_cancel").
Method string `json:"method"`
// Payload is the opaque, byte-identical clob_* frame forwarded verbatim.
Payload []byte `json:"payload"`
// CollateralRef references the Import whose locked value backs this order.
CollateralRef ids.ID `json:"collateralRef"`
}
RelayOrderTx forwards an opaque clob_* ZAP payload to the d-chain matcher, bound to a locked-collateral reference. The payload is the byte-identical clob_submit/clob_place frame the d-chain's zap_server.go expects; the proxy is pure transport and does not interpret it beyond routing.
func NewRelayOrderTx ¶ added in v1.3.8
func NewRelayOrderTx(from ids.ShortID, nonce uint64, method string, payload []byte, collateralRef ids.ID) *RelayOrderTx
NewRelayOrderTx creates a new relay-order transaction.
func (*RelayOrderTx) Verify ¶ added in v1.3.8
func (tx *RelayOrderTx) Verify() error
type Tx ¶
type Tx interface {
// ID returns the unique identifier for this transaction.
ID() ids.ID
// Type returns the transaction type.
Type() TxType
// Sender returns the sender's address.
Sender() ids.ShortID
// Timestamp returns when the transaction was created.
Timestamp() int64
// Bytes returns the serialized transaction.
Bytes() []byte
// Verify validates the transaction.
Verify() error
}
Tx is the interface for all DEX proxy transactions.
type TxType ¶
type TxType uint8
TxType represents the type of transaction.
const ( // TxImport claims value exported from C-Chain into the proxy (atomic // shared-memory import leg). Consumes imported UTXOs, credits local outputs. TxImport TxType = iota // TxExport settles proceeds back to C-Chain (atomic shared-memory export // leg). Produces exported outputs derived ONLY from confirmed d-chain fills. TxExport // TxRelayOrder forwards an opaque clob_* ZAP payload to the d-chain matcher, // bound to a locked-collateral reference. Transport only — no local match. TxRelayOrder // TxPlaceOrder is a thin relay envelope for a CLOB limit-order placement. TxPlaceOrder // TxCancelOrder is a thin relay envelope for a CLOB cancel. TxCancelOrder )
Source Files