@lifi/perps-types 11.3.0 → 11.4.0

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": "11.3.0",
+  "version": "11.4.0",
   "description": "Shared types for the LI.FI perps stack",
   "keywords": [
     "lifi",

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'
 
 /**
@@ -630,6 +631,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
   [ActionType.SYNC_FEE_ATTRIBUTION]: Record<string, never>
 }
 

package/src/enums.ts

@@ -175,6 +175,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',
   /** Never projected on `Provider.setup` or `Provider.options`, and never offered as a user-facing trading action. */
   SYNC_FEE_ATTRIBUTION = 'syncFeeAttribution',
 }

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

package/src/referral.ts

@@ -0,0 +1,266 @@
+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 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 const onboardTypeFields: readonly TypedDataParameter[] = [
+  { name: 'action', type: 'string' },
+  { name: 'account', type: 'address' },
+  { name: 'termsVersion', type: 'string' },
+  { name: 'referralCode', type: 'string' },
+  { name: 'nonce', type: 'uint256' },
+  { name: 'deadline', type: 'uint256' },
+]
+
+/**
+ * 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 const createReferralCodeTypeFields: readonly TypedDataParameter[] = [
+  { name: 'action', type: 'string' },
+  { name: 'account', type: 'address' },
+  { name: 'code', type: 'string' },
+  { name: 'nonce', type: 'uint256' },
+  { name: 'deadline', type: 'uint256' },
+]
+
+/**
+ * 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
+}