@lifi/perps-types 0.0.0-preview-c72bc0b → 0.0.0-preview-e6f120b

package/dist/types/metaProvider.d.ts

@@ -1,3 +1,4 @@
+import type { ActionType } from './enums.js';
 /**
  * Sentinel sent in the `provider` field for provider-independent actions
  * (e.g. {@link "./enums.js".ActionType.META_ACCEPT_TERMS}). The backend
@@ -7,4 +8,11 @@
 export declare const META_PROVIDER = "meta";
 /** Type alias for the {@link META_PROVIDER} provider-independent sentinel. @public */
 export type MetaProvider = typeof META_PROVIDER;
+/**
+ * The provider-independent actions dispatched with the {@link META_PROVIDER}
+ * sentinel. They carry no venue plugin and no `ProviderAction` descriptor, so
+ * they are signed as EIP-712 typed data with the end-user's wallet.
+ * @public
+ */
+export type MetaActionType = ActionType.META_ACCEPT_TERMS | ActionType.META_ONBOARD | ActionType.META_CREATE_REFERRAL_CODE;
 //# sourceMappingURL=metaProvider.d.ts.map

package/dist/types/metaProvider.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"metaProvider.d.ts","sourceRoot":"","sources":["../../src/metaProvider.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,eAAO,MAAM,aAAa,SAAS,CAAA;AAEnC,sFAAsF;AACtF,MAAM,MAAM,YAAY,GAAG,OAAO,aAAa,CAAA"}
+{"version":3,"file":"metaProvider.d.ts","sourceRoot":"","sources":["../../src/metaProvider.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAA;AAE5C;;;;;GAKG;AACH,eAAO,MAAM,aAAa,SAAS,CAAA;AAEnC,sFAAsF;AACtF,MAAM,MAAM,YAAY,GAAG,OAAO,aAAa,CAAA;AAE/C;;;;;GAKG;AACH,MAAM,MAAM,cAAc,GACtB,UAAU,CAAC,iBAAiB,GAC5B,UAAU,CAAC,YAAY,GACvB,UAAU,CAAC,yBAAyB,CAAA"}

package/dist/types/referral.d.ts

@@ -0,0 +1,237 @@
+import type { Pagination } from './account.js';
+import type { Address } from './primitives.js';
+import type { PerpsTypedData, TypedDataParameter } from './typedData.js';
+/**
+ * Reason the backend will not attach a candidate internal referral code to an
+ * address. The backend decides; the SDK relays the verdict.
+ * @public
+ */
+export declare enum ReferralCodeRejection {
+    /** The candidate does not match the accepted code format. */
+    MALFORMED = "MALFORMED",
+    /** No internal referral code matches the candidate. */
+    NOT_FOUND = "NOT_FOUND",
+    /** The code exists but the backend has disabled it. */
+    INACTIVE = "INACTIVE",
+    /** The candidate is the queried address's own code. */
+    SELF_REFERRAL = "SELF_REFERRAL",
+    /** The address already has an attached code; attachment is first-touch. */
+    ALREADY_ATTACHED = "ALREADY_ATTACHED",
+    /** The address no longer meets the backend's conditions for attachment. */
+    NOT_ELIGIBLE = "NOT_ELIGIBLE"
+}
+/**
+ * Backend verdict for a candidate internal referral code.
+ * @public
+ */
+export interface ReferralCodeValidation {
+    /** The candidate exactly as submitted. */
+    code: string;
+    valid: boolean;
+    /** Backend-normalized form of `code`; absent when `valid` is false. */
+    normalizedCode?: string;
+    /** Present only when `valid` is false. */
+    rejection?: ReferralCodeRejection;
+}
+/**
+ * The internal referral code attached to an address. Attachment is first-touch:
+ * once the backend records it, it does not change.
+ * @public
+ */
+export interface AttachedReferralCode {
+    /** Normalized code this address is attached to. */
+    code: string;
+    /** Unix epoch milliseconds the attachment was recorded. */
+    attachedAt: number;
+}
+/**
+ * The shareable internal referral code an address owns.
+ * @public
+ */
+export interface OwnedReferralCode {
+    code: string;
+    /** Unix epoch milliseconds the code was created. */
+    createdAt: number;
+    /** Number of addresses attached to this code. */
+    attachedCount: number;
+}
+/**
+ * Whether an address may create an owned internal referral code. The backend
+ * owns both the threshold and the decision.
+ * @public
+ */
+export interface OwnedReferralCodeEligibility {
+    eligible: boolean;
+    /**
+     * Executed notional the address must reach, as a decimal string in the
+     * backend's reporting currency. Absent when the backend does not disclose it.
+     */
+    requiredNotional?: string;
+    /** The address's executed notional so far, in the same units as `requiredNotional`. */
+    currentNotional?: string;
+}
+/**
+ * What the one pending onboarding signature would commit for an address. A
+ * present field is carried by the step; an absent field is not part of it.
+ * @public
+ */
+export interface OnboardingRequirement {
+    /** Terms version the step accepts; absent when the address already accepted the current version. */
+    termsVersion?: string;
+    /** Normalized code the step attaches; absent when the step attaches none. */
+    referralCode?: string;
+}
+/**
+ * Address-scoped onboarding and internal-referral state, served by
+ * `GET /v1/perps/meta/referral?address=`.
+ *
+ * An address the backend holds no record for still resolves to a well-formed
+ * payload: `termsAccepted` is `false` and every optional state field is absent.
+ * @public
+ */
+export interface ReferralStatus {
+    address: Address;
+    /** Backend-owned version identifier for the current terms. */
+    termsVersion: string;
+    termsAccepted: boolean;
+    attachedCode?: AttachedReferralCode;
+    ownedCode?: OwnedReferralCode;
+    ownedCodeEligibility: OwnedReferralCodeEligibility;
+    /** Verdict for the request's candidate code; absent when the request passed none. */
+    candidate?: ReferralCodeValidation;
+    /**
+     * The one onboarding step to sign next; absent when the backend requires no
+     * consent from this address.
+     */
+    onboarding?: OnboardingRequirement;
+}
+/**
+ * One address attached to the queried address's owned internal referral code.
+ * @public
+ */
+export interface ReferralActivityItem {
+    address: Address;
+    /** Unix epoch milliseconds the attachment was recorded. */
+    attachedAt: number;
+    /**
+     * Executed notional recorded against this attachment, as a decimal string in
+     * the backend's reporting currency.
+     */
+    notional: string;
+}
+/**
+ * Paginated attachment records for an address's owned internal referral code,
+ * served by `GET /v1/perps/meta/referral/activity?address=`.
+ *
+ * An address that owns no code resolves to `items: []` with `hasMore: false`
+ * and no cursor.
+ * @public
+ */
+export interface ReferralActivityResponse {
+    items: ReferralActivityItem[];
+    pagination: Pagination;
+}
+/**
+ * Params for an {@link "./enums.js".ActionType.META_ONBOARD} action: the terms
+ * version to accept and the candidate internal referral code to attach.
+ *
+ * Both fields are requests, not commitments. The backend decides what the step
+ * it returns actually carries, and returns no step when it needs no consent.
+ *
+ * Provider-independent: sent with the {@link "./metaProvider.js".META_PROVIDER}
+ * sentinel in the transport `provider` field.
+ * @public
+ */
+export interface OnboardParams {
+    /** Terms-of-Service version being accepted; backend-owned, relayed verbatim. */
+    termsVersion?: string;
+    /** Candidate code as the client captured it; the backend normalizes it. */
+    referralCode?: string;
+}
+/**
+ * EIP-712 message body for an `Onboard`. Field order matches
+ * {@link onboardTypeFields}.
+ *
+ * Every mutable field is bound into the digest, so a term the signature does
+ * not commit is carried as the empty string rather than dropped.
+ * @public
+ */
+export interface OnboardMessage {
+    /** Human-readable action, e.g. `"Accept LI.FI Perps Terms of Service v3"`. */
+    action: string;
+    account: Address;
+    /** Terms version accepted, or `''` when the signature accepts no terms. */
+    termsVersion: string;
+    /** Normalized code attached, or `''` when the signature attaches none. */
+    referralCode: string;
+    /** Replay-protection nonce as a decimal string (uint256). */
+    nonce: string;
+    /** Unix timestamp in milliseconds after which the signature is stale. */
+    deadline: number;
+}
+/**
+ * EIP-712 type member list for the `Onboard` primary type. Field order is part
+ * of the signed digest and must match the backend's encoder.
+ * @public
+ */
+export declare const onboardTypeFields: readonly TypedDataParameter[];
+/**
+ * EIP-712 typed data for a composite onboarding consent, as returned by
+ * `createAction` and signed client-side. `primaryType` is always `'Onboard'`.
+ * @public
+ */
+export interface OnboardTypedData extends PerpsTypedData {
+    primaryType: 'Onboard';
+    types: {
+        Onboard: readonly TypedDataParameter[];
+    } & PerpsTypedData['types'];
+    message: OnboardMessage;
+}
+/**
+ * Params for an
+ * {@link "./enums.js".ActionType.META_CREATE_REFERRAL_CODE} action.
+ *
+ * Provider-independent: sent with the {@link "./metaProvider.js".META_PROVIDER}
+ * sentinel in the transport `provider` field.
+ * @public
+ */
+export interface CreateReferralCodeParams {
+    /** Desired code; omit to let the backend generate one. */
+    code?: string;
+}
+/**
+ * EIP-712 message body for a `CreateReferralCode`. Field order matches
+ * {@link createReferralCodeTypeFields}.
+ * @public
+ */
+export interface CreateReferralCodeMessage {
+    /** Human-readable action, e.g. `"Create LI.FI Perps referral code ABC123"`. */
+    action: string;
+    account: Address;
+    /** Normalized code the signature reserves. */
+    code: string;
+    /** Replay-protection nonce as a decimal string (uint256). */
+    nonce: string;
+    /** Unix timestamp in milliseconds after which the signature is stale. */
+    deadline: number;
+}
+/**
+ * EIP-712 type member list for the `CreateReferralCode` primary type. Field
+ * order is part of the signed digest and must match the backend's encoder.
+ * @public
+ */
+export declare const createReferralCodeTypeFields: readonly TypedDataParameter[];
+/**
+ * EIP-712 typed data for reserving an owned internal referral code, as
+ * returned by `createAction` and signed client-side. `primaryType` is always
+ * `'CreateReferralCode'`.
+ * @public
+ */
+export interface CreateReferralCodeTypedData extends PerpsTypedData {
+    primaryType: 'CreateReferralCode';
+    types: {
+        CreateReferralCode: readonly TypedDataParameter[];
+    } & PerpsTypedData['types'];
+    message: CreateReferralCodeMessage;
+}
+//# sourceMappingURL=referral.d.ts.map

package/dist/types/referral.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"referral.d.ts","sourceRoot":"","sources":["../../src/referral.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lifi/perps-types",
-  "version": "0.0.0-preview-c72bc0b",
+  "version": "0.0.0-preview-e6f120b",
   "description": "Shared types for the LI.FI perps stack",
   "keywords": [
     "lifi",

package/src/account.ts

@@ -218,6 +218,25 @@ export interface OrdersResponse {
   pagination: Pagination
 }
 
+/**
+ * Fee a venue charged, in the asset the venue charged it in. A venue does not
+ * always charge a fee in the asset the record is otherwise denominated in, so
+ * a consumer must format the amount against `asset` and never against the
+ * fill's quote asset or the activity's own `asset`.
+ *
+ * @public
+ */
+export interface Fee {
+  /** Decimal string in `asset`'s units. */
+  amount: string
+  /**
+   * Display symbol the fee is denominated in, resolved by the provider
+   * adapter. Falls back to the venue's own asset id when the registry knows no
+   * symbol.
+   */
+  asset: string
+}
+
 /**
  * Normalized execution/fill record for an order.
  *
@@ -239,7 +258,8 @@ export interface Fill {
   status: FillStatus
   liquidity: LiquidityRole
   filledSize?: string
-  fee?: string
+  /** Absent when the venue reports no fee for the fill. */
+  fee?: Fee
   realizedPnl?: string | null
   startPosition?: string
   classification: FillClassification
@@ -304,9 +324,8 @@ export interface DepositActivity extends BaseActivity {
 }
 
 /**
- * Account activity representing a completed withdrawal. `amount` and `fee`
- * are decimal strings in `asset`'s units — a withdrawal fee is always
- * denominated in the withdrawn asset.
+ * Account activity representing a completed withdrawal. `amount` is a decimal
+ * string in `asset`'s units.
  *
  * @public
  */
@@ -319,7 +338,7 @@ export interface WithdrawalActivity extends BaseActivity {
   asset: string
   amount: string
   /** Absent when the venue reports no fee for the withdrawal. */
-  fee?: string
+  fee?: Fee
   /** Fully-resolved block-explorer URL for the on-chain withdrawal tx. */
   explorerLink?: string
 }
@@ -336,11 +355,10 @@ export interface LiquidatedPosition {
 }
 
 /**
- * Account activity representing a liquidation event. `liquidatedPositions` is
- * never empty: a provider adapter drops any record whose positions it cannot
- * identify. A venue that liquidates several cross-margin positions in one
- * cascade reports them as one activity with several entries, so consumers
- * must never group activities by timestamp.
+ * Account activity representing a liquidation event. A venue that liquidates
+ * several cross-margin positions in one cascade reports them as one activity
+ * with several entries, so consumers must never group activities by
+ * timestamp.
  *
  * @public
  */
@@ -357,7 +375,11 @@ export interface LiquidationActivity extends BaseActivity {
    * liquidation row.
    */
   leverageType?: string
-  liquidatedPositions: LiquidatedPosition[]
+  /**
+   * At least one entry is guaranteed — a provider adapter drops any
+   * liquidation record whose positions it cannot resolve to a known market.
+   */
+  liquidatedPositions: [LiquidatedPosition, ...LiquidatedPosition[]]
 }
 
 /**
@@ -393,6 +415,14 @@ export type TransferActivity = BaseActivity & {
   direction: 'IN' | 'OUT'
   asset: string
   amount: string
+  /**
+   * Every fee the venue charged for the transfer, in the order the venue
+   * reports them. A venue may charge several fees for one transfer, each in a
+   * different asset — a transfer fee plus a separate gas fee in the chain's
+   * native token — so this is a list and not a single amount. Absent when the
+   * venue reports no fee.
+   */
+  fees?: Fee[]
   meta?: Record<string, unknown>
   /** Fully-resolved block-explorer URL for the on-chain transfer tx. */
   explorerLink?: string

package/src/action.ts

@@ -12,6 +12,7 @@ import type {
 } from './enums.js'
 import type { MarketDisplay, MarketRef } from './market.js'
 import type { Address, Hex } from './primitives.js'
+import type { CreateReferralCodeParams, OnboardParams } from './referral.js'
 import type { PerpsTypedData } from './typedData.js'
 
 /**
@@ -616,6 +617,8 @@ export interface ActionParamsMap {
   [ActionType.ACCEPT_PROVIDER_TERMS]: Record<string, never>
   [ActionType.DEPOSIT]: DepositParams
   [ActionType.META_ACCEPT_TERMS]: AcceptTermsParams
+  [ActionType.META_ONBOARD]: OnboardParams
+  [ActionType.META_CREATE_REFERRAL_CODE]: CreateReferralCodeParams
 }
 
 /**

package/src/enums.ts

@@ -173,6 +173,10 @@ export enum ActionType {
   DEPOSIT = 'deposit',
   /** Provider-independent: sent with the `META_PROVIDER` sentinel, not a real provider key. */
   META_ACCEPT_TERMS = 'metaAcceptTerms',
+  /** Provider-independent composite onboarding consent: the current app-wide terms plus an optional internal referral code, in one signature. */
+  META_ONBOARD = 'metaOnboard',
+  /** Provider-independent: reserves the shareable internal referral code an address owns. */
+  META_CREATE_REFERRAL_CODE = 'metaCreateReferralCode',
 }
 
 /** Price relation that activates a trigger order. @public */

package/src/index.ts

@@ -20,5 +20,6 @@ export * from './positionMargin.js'
 export * from './primitives.js'
 export * from './providers.js'
 export * from './quote.js'
+export * from './referral.js'
 export * from './subscriptions.js'
 export * from './typedData.js'

package/src/metaProvider.ts

@@ -1,3 +1,5 @@
+import type { ActionType } from './enums.js'
+
 /**
  * Sentinel sent in the `provider` field for provider-independent actions
  * (e.g. {@link "./enums.js".ActionType.META_ACCEPT_TERMS}). The backend
@@ -8,3 +10,14 @@ export const META_PROVIDER = 'meta'
 
 /** Type alias for the {@link META_PROVIDER} provider-independent sentinel. @public */
 export type MetaProvider = typeof META_PROVIDER
+
+/**
+ * The provider-independent actions dispatched with the {@link META_PROVIDER}
+ * sentinel. They carry no venue plugin and no `ProviderAction` descriptor, so
+ * they are signed as EIP-712 typed data with the end-user's wallet.
+ * @public
+ */
+export type MetaActionType =
+  | ActionType.META_ACCEPT_TERMS
+  | ActionType.META_ONBOARD
+  | ActionType.META_CREATE_REFERRAL_CODE