Lit Actions in Relay

Relay currently uses Lit Actions for two separate protocol components:

| Component | Purpose | | ----------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | lit-allocator | Derives protocol-controlled wallets and signs allocator withdrawals after verifying the oracle attestation and the hashes produced by the Hub allocator flow. | | lit-deposit-address | Derives per-order deposit wallets and signs transactions that move funds from those wallets into the protocol after verifying the Hub deposit trigger, oracle attestation, order, and transaction policy. |

These components have different source code, policies, environment configuration, Lit registrations, and integration flows. A change to one does not automatically update the other.

The @relay-protocol/lit-actions package is not another Lit Action. It is the release package that bundles the latest active versions of both components for their supported environments and VM types. Protocol services should consume action code and configuration from this package instead of copying bundles from the source packages.

How they are used

For both components, the basic flow is:

1. A caller selects the component, protocol environment, version, and VM type.
2. @relay-protocol/lit-actions returns the corresponding bundled JavaScript code and its environment configuration.
3. The caller sends the code, request parameters, PKP id, and usage API key to Lit Protocol.
4. The action runs inside Lit's TEE, retrieves the PKP private key, validates the component-specific request and oracle attestation, and signs only if all checks pass.
5. The caller submits the signed transaction or payload to the destination chain.

The PKP private key and derived private keys do not leave the TEE. Contract addresses, Hub chain id, allowed oracles, and signature threshold are compiled into each environment-specific bundle and cannot be supplied by the caller.

Packaged environments

The current package exposes the following matrix:

| Component | Environments | Versions | VM types | | --------------- | --------------------- | ------------ | --------------------------------------------------------------------------------------- | | Allocator | dev, stag, prod | v1, v2 | Bitcoin, Ethereum, Gateway, Hedera, Hyperliquid, Lighter, Solana, TON, Tron, XRP | | Allocator | dev | v3 | Atlas, Bitcoin, Ethereum, Gateway, Hedera, Hyperliquid, Lighter, Solana, TON, Tron, XRP | | Allocator | test | v1, v2 | Ethereum (v1), Atlas (v2) | | Deposit address | dev, stag, prod | v1, v1.1 | Bitcoin, Ethereum, Hyperliquid, Solana, TON, Tron | | Deposit address | dev, stag, prod | v1.2 | Bitcoin, Ethereum, Hyperliquid, Solana, TON, Tron, XRP |

Each component and environment produces different action code because its configuration is embedded at build time.

A version is either built from the source package on every generation, or frozen: copied verbatim from an exact published version of this package so its CIDs never move. Allocator v1 and v2 are frozen from 0.0.41 in every environment (v1 as first published in 0.0.32 plus the gateway-vm bundle it shares with v2; v2 adds multi-gateway Lighter support, lighterGateways). They sign for the allocator each environment ran before the Hub-chain core redeploy (DEC-1891). Test v2 is the exception: test still runs that allocator, so its atlas-vm v2 is built from source and signs the Oct 29 Atlas format. Allocator v3 is frozen from 0.0.42 for dev only and signs for dev's redeployed allocator; callers pick v2 or v3 by the allocator a withdrawal was submitted to. Deposit-address v1 actions are frozen from 0.0.36; deposit-address v1.1 is frozen from 0.0.39: it lets a Bitcoin sweep pay change back to the deposit address and adds the refund, deadline, price-decimal and sweep-metadata checks merged since 0.0.36 (#845, #872, #875) on every VM. Deposit-address v1.2 lets a Solana sweep carry a capped priority fee (ComputeBudget instructions before the deposit) and packages XRP derivation and native Payment sweep signing for dev, stag, and prod (#971); XRP is absent from the frozen v1 and v1.1 versions. Since 0.0.44 it widens the XRP sweep ledger window from 4 to 32 ledgers (#989). Since 0.0.45, only its XRP bundle is built from current source in each environment; every other VM is frozen from 0.0.44. XRP rejects priceImpactBps of 10000 (#972), while the other VM bundles retain their published behavior allowing that boundary value.

The published 0.0.44 bundles omitted the stricter price-impact rejection and therefore differ from the locally built bundles registered by the dev 024 manifest. Version 0.0.45 restores the registered dev XRP bundle; its CID is QmP35VVrREUaf5FUiSeS3NP4kif8FeJPxS8idSZNuXSXkU. XRP callers that create exact_output addresses with priceImpactBps 10000 must change before adopting 0.0.45. Each environment must have its rebuilt XRP v1.2 CID registered before callers adopt the release; dev's 024 manifest already registers it. Which entries are frozen is declared in the KINDS matrix in scripts/generate-actions.ts; generation fails if a frozen version cannot be fetched.

Important: every code change requires redeployment

Treat every Lit Action code change, however small, as a full deployment and integration change.

Follow the concrete deployment checklist for every affected environment.

Lit Action registrations are content-addressed. Changing action source, bundled dependencies, imported dependency versions, or embedded environment configuration changes the final bundle and therefore its CID. Existing registrations and integrations continue to point at the old code.

For every affected component, environment, and VM type, a change requires:

1. building the new action bundle;
2. registering/deploying the new bundle with Lit;
3. updating @relay-protocol/lit-actions to package the active bundle and configuration;
4. publishing and adopting the new package version in every caller;
5. updating any configured action CIDs or related integration values; and
6. running the complete end-to-end integration flow before switching traffic.

Do not assume that a source-only change is live after merging or publishing this repository. The new action must be deployed and every consumer must be integrated with it.

Package API

getAllocatorAction(environment, version, vmType)
getDepositAddressAction(environment, version, vmType)

Each helper returns:

• code: the exact bundled JavaScript source to execute;
• config: the environment configuration compiled into that bundle.

Example:

import { getAllocatorAction } from "@relay-protocol/lit-actions"
import { VmType } from "@relay-protocol/settlement-sdk"

const vmType: VmType = "ethereum-vm"
const action = getAllocatorAction("dev", "v2", vmType)

console.log(action.code)
console.log(action.config)

The helpers throw if the requested component, environment, version, or VM type is not packaged.

Updating this package

The action source remains in lit-allocator and lit-deposit-address. During generation, this package runs their bundlers, reads the generated per-VM code and environment configuration, and writes src/generated.ts.

yarn workspace @relay-protocol/lit-actions generate
yarn workspace @relay-protocol/lit-actions build

src/generated.ts is generated and must not be edited manually. To change the packaged environments, versions, or VM types, update the KINDS matrix in scripts/generate-actions.ts.

yarn workspace @relay-protocol/lit-actions lint type-checks the generation scripts under scripts/ against tsconfig.scripts.json.