SessionsContract class

SessionsContract — time-limited trading sessions over a canonical Account.

An Account owner authorizes an ephemeral address to submit a bounded set of transactions on the Account's behalf until a fixed expiry. The session key never receives a reusable Auth: each wrapper mints app authorization internally and consumes it in the same call.

WHAT A SESSION KEY CAN DO. It cannot withdraw to an address, cannot grant or revoke sessions, and cannot outlive its expiry — those all require owner auth. It CAN trade the Account's full balance: the spot wrappers take a caller-chosen Pool and, through deepbook_core_account, pull the account's entire Base, Quote and DEEP balance (stored plus unsettled) into the embedded manager for the duration of the call, with price_limit supplied by the caller. Nothing caps notional, restricts which pools are reachable, or bounds loss to adverse pricing. Treat a session key as authority over everything the Account holds, and fund an ephemeral-session Account accordingly.

Operational precondition: an admin must have authorized SessionsApp on the account registry. Until then — or after a deauthorize_app — the TRADING wrappers abort with EAppNotAuthorized; authorizeSession, revokeSession and sessionExpirationMs use owner auth or no auth and keep working. Note that deauthorize_app does not clear SessionsData, so re-authorizing makes every still-unexpired grant live again at once — it is a pause, not a kill switch. Revoking, and reading expirations, also keep working if the sessions package is later version-gated.

This class wraps the session lifecycle and the Predict entrypoints. The DeepBook spot session wrappers are generated (see the flat-exported placeLimitOrder / placeMarketOrder / cancelLiveOrder / cancelLiveOrders / withdrawSettledAmounts builders) but are not wrapped here — note placeLimitOrder and placeMarketOrder put accountRegistry at index 2 and sessionsConfig at 4, because deepbookRegistry sits between them; the other three take no deepbookRegistry and so keep 1 and 3 like the Predict wrappers: the surrounding spot-over-Account workflow — discovering the embedded balance manager, reading resting orders and locked balances — is not modelled yet, so a wrapped builder would be hard to use well. They are reachable from the generated bindings meanwhile.

Constructors

SessionsContract(SessionsConfig _config)

Properties

hashCode → int

The hash code for this object.

no setter, inherited

runtimeType → Type

A representation of the runtime type of the object.

no setter, inherited

Methods

authorizeSession({required String wrapperId, required String session, required Object durationMs}) → void Function(Transaction)

Grant session authority over the Account until now + durationMs. Authority is derived from the transaction SENDER, so the owner must sign this. durationMs (int or BigInt, raw milliseconds) must be > 0 and <= MAX_SESSION_DURATION_MS; an Account holds at most MAX_SESSIONS_PER_ACCOUNT distinct addresses. Re-authorizing an address replaces its expiry in place and consumes no additional slot.

deriveAccountId(String owner) → String

The owner's canonical ACCOUNT id — a different derived object from the wrapper. The session grants hang off this one, so this is what deriveSessionsFieldId and decodeSessions work from.

deriveAccountWrapperId(String owner) → String

The owner's canonical AccountWrapper id — derived off-chain, no read. Every builder here takes that id.

deriveSessionsFieldId(String owner) → String

The object id of the owner's DataKey<SessionsApp> dynamic field — fetch this object and pass its BCS contents to decodeSessions. There is no bulk on-chain read, so this is the route to enumerating grants.

mintExactAmount({required String expiryMarketId, required String wrapperId, required String protocolConfig, required dynamic pricer, required Object lowerTick, required Object higherTick, required Object maxPremium, required Object minQuantity, required Object maxCost}) → TransactionResult Function(Transaction)

Mint by spending up to a premium budget, flooring the quantity received. The chain requires maxCost > 0. Amounts are raw Move units, int or BigInt.

mintExactCost({required String expiryMarketId, required String wrapperId, required String protocolConfig, required dynamic pricer, required Object lowerTick, required Object higherTick, required Object maxCost, required Object minQuantity}) → TransactionResult Function(Transaction)

Mint within an all-in budget as a session. Amounts are raw Move units. Requires Sessions/Predict v2 or later.

mintExactQuantity({required String expiryMarketId, required String wrapperId, required String protocolConfig, required dynamic pricer, required Object lowerTick, required Object higherTick, required Object quantity, required Object maxCost, required Object maxProbability}) → TransactionResult Function(Transaction)

Mint a position of an exact payout quantity, as session. Pass u64 max (BigInt.parse('18446744073709551615')) for maxCost / maxProbability to leave either slippage cap effectively unbounded — the chain asserts value <= cap, so the max value can never trip. Both are required; there is no default. Quantities are raw Move units, int or BigInt.

noSuchMethod(Invocation invocation) → dynamic

Invoked when a nonexistent method or property is accessed.

inherited

redeemLive({required String expiryMarketId, required String wrapperId, required String protocolConfig, required dynamic pricer, required BigInt orderId, required Object closeQuantity, Object? minProbability, Object? minProceeds}) → TransactionResult Function(Transaction)

Close part or all of a live position at the pricer's mark, as session. minProbability / minProceeds are close-side slippage floors; 0 disables either, and OMITTING them is 0 — unlike the mint caps, which are required. On a delegated key this is the direction that closes a position at any price, so pass real floors unless you mean to accept whatever the mark gives you.

redeemSettled({required String expiryMarketId, required String wrapperId, required String protocolConfig, required BigInt orderId}) → void Function(Transaction)

Claim a settled position in full, as session. Takes no pricer — the settlement price is fixed — and no quantity: a settled claim is all-or-nothing.

revokeSession({required String wrapperId, required String session}) → void Function(Transaction)

Remove session's grant. Owner-signed, like authorizeSession. Deliberately takes no SessionsConfig: revocation is not version-gated, so it keeps working after the package is retired. Revoking an address that holds no grant is a silent no-op — it neither aborts nor emits, so read before and after if you need to distinguish "revoked" from "was never granted".

sessionExpirationMs({required String wrapperId, required String session}) → TransactionResult Function(Transaction)

Read one session's absolute expiry as Option<u64>. Compose in a dev-inspect/simulate PTB and decode the returned BCS. Not version-gated.

toString() → String

A string representation of this object.

inherited

Operators

operator ==(Object other) → bool

The equality operator.

inherited

Static Methods

activeSessions(List<SessionGrant> grants, Object nowMs) → List<SessionGrant>

Grants from decodeSessions that are still live at nowMs (int or BigInt, ms since epoch).

decodeSessions(Uint8List contents) → List<SessionGrant>

Decode an Account's stored grants from the raw BCS content of its DataKey<SessionsApp> dynamic FIELD object — the whole Field<DataKey<SessionsApp>, SessionsData>, as the core API returns it, not the inner SessionsData. Get the id from deriveSessionsFieldId.

expiredSessions(List<SessionGrant> grants, Object nowMs) → List<SessionGrant>

Grants that are already dead at nowMs — the complement of activeSessions, and the list to revoke when reclaiming slots. Use this rather than filtering by hand: nowMs > expiresAtMs looks equivalent but leaves the grant expiring exactly at nowMs occupying a slot forever.