Class: Swaps

Executes queued current-contract RequestTrade operations through the Chain Gateway.

Constructors

Constructor

new Swaps(gateway, symbols, signer?, walletAddress?, options?): Swaps

Creates a swap service.

Parameters

Parameter	Type
gateway	SwapGateway
symbols	TokenResolver
signer?	GalaChainSigner
walletAddress?	string
options?	UniqueKeyOptions

Returns

Swaps

Example

const swaps = new Swaps(gateway, symbols, signer, 'client|alice');

Methods

buildSwap()

buildSwap(tokenIn, tokenOut, fee, amount, options?): Promise<RequestTradeDTO>

Builds the RequestTrade DTO that swap would sign, without signing or sending it: to show in an approval popup, to remember its uniqueKey, or to sign elsewhere. Submit exactly this DTO with submitSwap. The pure counterpart, with canonical inputs and no resolution, is buildRequestTradeDto.

Parameters

Parameter	Type
tokenIn	TokenRef
tokenOut	TokenRef
fee	FEE_TIER
amount	SwapAmount
options?	SwapOptions

Returns

Promise<RequestTradeDTO>

Example

const dto = await swaps.buildSwap('GALA', 'GUSDC', 3000, { exactIn: '100' });
showApproval(dto);
const submitted = await swaps.submitSwap(dto);

---

confirmSwap()

confirmSwap(uniqueKey, options?): Promise<AppliedTrade>

Confirm a swap by its durable uniqueKey without resubmitting it. This is the recovery path after a CONFIRMATION_TIMEOUT, a SUBMISSION_OUTCOME_UNKNOWN, a 409 replay conflict, or a process restart: it reads the same apply-results record that SubmittedTransaction.confirm() reads (retained for 7 days) and resolves the applied trade or throws the chain's rejection. The first read happens immediately unless initialDelayMs is given.

Parameters

Parameter	Type
uniqueKey	string
options?	ConfirmOptions

Returns

Promise<AppliedTrade>

Example

const applied = await swaps.confirmSwap('galaswap-operation-2f1c…');

---

submitSwap()

submitSwap(dto): Promise<SubmittedTransaction<AppliedTrade>>

Signs and submits a DTO built by buildSwap or buildRequestTradeDto. The DTO must be exactly what the builder produces (no signature, canonical decimals, builder key order), so what an app showed is what gets signed.

Parameters

Parameter	Type
dto	RequestTradeDTO

Returns

Promise<SubmittedTransaction<AppliedTrade>>

Example

const submitted = await swaps.submitSwap(dto);
const applied = await submitted.confirm();

---

submitSwapShadow()

submitSwapShadow(dto): Promise<ShadowSubmitOutcome>

Signs and shadow-submits a DTO built by buildSwap; see swapShadow.

Parameters

Parameter	Type
dto	RequestTradeDTO

Returns

Promise<ShadowSubmitOutcome>

---

swap()

swap(tokenIn, tokenOut, fee, amount, options?): Promise<SubmittedTransaction<AppliedTrade>>

Signs and submits an exact-input or exact-output RequestTrade DTO. The returned transaction is QUEUED; call await tx.confirm() to obtain the executed trade or chain rejection.

Parameters

Parameter	Type
tokenIn	TokenRef
tokenOut	TokenRef
fee	FEE_TIER
amount	SwapAmount
options?	SwapOptions

Returns

Promise<SubmittedTransaction<AppliedTrade>>

Example

const submitted = await swaps.swap('GALA', 'GUSDC', 3000, {
  exactIn: '100',
  amountOutMinimum: '14',
});

---

swapShadow()

swapShadow(tokenIn, tokenOut, fee, amount, options?): Promise<ShadowSubmitOutcome>

Signs and submits a SHADOW (dark) swap: the same RequestTrade as swap, relayed with X-Shadow: true so the swap backend marks it private before it reaches the contract. Requires a walletAddress. Resolves the normalized outcome instead of throwing on a gateway refusal: ok: false carries unavailable (retryable), disabled, rejected (with the gateway's message) or unknown. A success carries queued, to be confirmed with confirmSwap(queued.uniqueKey); never fall back to a public swap on failure. Whatever this THROWS (a validation error, the signer, a lost connection, SHADOW_NOT_QUEUED) has error.shadow === true (isShadowError), so an app can apply its dark-swap policy to it.

Parameters

Parameter	Type
tokenIn	TokenRef
tokenOut	TokenRef
fee	FEE_TIER
amount	SwapAmount
options?	SwapOptions

Returns

Promise<ShadowSubmitOutcome>

Example

const outcome = await swaps.swapShadow('GALA', 'GUSDC', 3000, { exactIn: '100' });
if (outcome.ok) await swaps.confirmSwap(outcome.queued.uniqueKey);