Resolver’lar için

Resolver’lar Aqua’da ne yapar

1inch Network genelinde Aqua likiditesini dolduran takaslar 1inch Resolver'larca yönlendirilir: 1inch doğrulama sürecini tamamlayan piyasa yapıcılar ve arbitrajcılar.

Aqua’nın kendisi keşif de eşleştirme de yapmaz. Her takas çağrısında tek bir pozisyonu tek bir karşı tarafa karşı fiyatlandırıp yürütür. Hangi pozisyonun hangi büyüklükte doldurulacağını bulmak resolver’ın işidir: 1inch yönlendirmesi takasları ağa iletir, kendi sistemleriniz de sözleşmeleri doğrudan çağırabilir.

Temel mekanikler size yeniyse şuradan başlayın: Aqua nasıl çalışır.

Başlamadan önce

• 1inch Business portalı üzerinden resolver doğrulaması; zincir başına erişim token’ı verir
• Takas işlemini gönderen operatör EOA’daki erişim token’ı
• Hedef zincirde düğüm erişimi, ayrıca doldurmalar için girdi token’ları ve gas
• Kanonik kontrat adresleri, desteklenen her zincirde aynı ve aşağıda listeli
• Aqua API keşif yolu için Business portal'dan alınan bir API anahtarı

Kontrat adresleri

Aqua ve SwapVM yönlendiricisi deterministik dağıtımlardır ve desteklenen her zincirde aynı adrese sahiptir. Yalnızca bu iki kontratla etkileşime geçin. Bunun dışındaki hiçbir şey Aqua değildir.

Aqua (kayıt defteri)

0x1111113ccf1426a8e30e2bff5e005d929bf6a90a

SwapVM yönlendiricisi

0x111111338c5091e8440b67b168bae16a668ac0de

Bir doldurma nasıl işler

1. 1

   Doğrulanın

   Business portalı üzerinden resolver katılımını tamamlayın ve doldurma yaptığınız her zincir için erişim token’ını alın.

2. 2

   Bir pozisyon keşfedin

   Açık pozisyonları Aqua API'den çekin, canlı kümeyi Shipped ve Docked olaylarından yeniden kurun veya ağ çözücüsü olarak 1inch yönlendirmesinden takas alın.

3. 3

   Göndermeden hemen önce fiyat alın

   Çözümlenmiş emirle yönlendiricinin quote fonksiyonunu static call ile çağırın. Fiyatlar canlı cüzdan desteğini okur; başka doldurmalar geldikçe değişir.

4. 4

   Sınırlarınızı belirleyin

   Taze fiyattan bir asgari çıktı türetin ve kısa bir son tarih koyun. Eğri kayarsa daha kötü bir kurdan dolmak yerine işlem geri alınır.

5. 5

   Takası yapın ve doğrulayın

   Takası erişim token’ını tutan EOA’dan gönderin, başarılı bir makbuz şart koşun ve gerçekleşen tutarları Swapped olayından okuyun.

Hızlı başlangıç: bir pozisyonu fiyatlayıp doldurun

Aşağıdaki örnekler Aqua API ile açık bir pozisyonu bulur, fiyat teklifi alır ve korumalı bir doldurma gönderir. Node 22 üzerinde TypeScript SDK'larıyla çalışır. Kontratlar, olaylar, SDK'lar ve API pozisyona strategy der, kod da öyle der.

pnpm add @1inch/aqua-sdk @1inch/swap-vm-sdk viem

import assert from 'node:assert'
import { HexString, Order } from '@1inch/swap-vm-sdk'

// Every currently open position from every LP, newest first. Auth is the
// same API key the other 1inch APIs use - issued in the Business portal.
const response = await fetch('https://api.1inch.com/aqua/v1.0/strategies/opened?chainIds=1&limit=50', {
  headers: { Authorization: `Bearer ${process.env.ONEINCH_API_KEY}` },
})
assert(response.ok, `Aqua API responded ${response.status}`)
const { items, nextCursor } = await response.json()

// Pick by your own criteria. Per-token balance and allowance in each item are
// useful pre-filters, but they are indexed with a delay - only a fresh
// on-chain quote() is authoritative.
const strategy = items[0]
const order = Order.decode(new HexString(strategy.strategyBytes))
console.log('candidate:', strategy.strategyHash, 'tokens:', strategy.tokens.length, 'more:', nextCursor !== null)

import assert from 'node:assert'
import { ABI, Address, HexString, Order, SwappedEvent, SwapVMContract, TakerTraits } from '@1inch/swap-vm-sdk'
import { createPublicClient, createWalletClient, decodeFunctionResult, erc20Abi, http, isHex } from 'viem'
import { privateKeyToAccount } from 'viem/accounts'
import { mainnet } from 'viem/chains'

// The SwapVM router is a deterministic deployment - the same address on every
// supported chain (see the contract addresses above). The strategy bytes come
// from the Aqua API or a Shipped event. The operator key belongs to the EOA
// holding the resolver credential - it must be the transaction origin.
const router = new Address('0x111111338c5091e8440b67b168bae16a668ac0de')
const strategyBytes = process.env.STRATEGY_BYTES
const operatorPrivateKey = process.env.OPERATOR_PRIVATE_KEY
assert(isHex(strategyBytes) && isHex(operatorPrivateKey))

const order = Order.decode(new HexString(strategyBytes))

const USDC = new Address('0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48')
const WETH = new Address('0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2')
const amountIn = 3_000n * 10n ** 6n

const operator = privateKeyToAccount(operatorPrivateKey)
const publicClient = createPublicClient({ chain: mainnet, transport: http() })
const wallet = createWalletClient({ chain: mainnet, transport: http(), account: operator })

// 1. Preview the swap with a static quote() call, right before you submit.
const quoteTx = SwapVMContract.buildQuoteTx(router, {
  order,
  tokenIn: USDC,
  tokenOut: WETH,
  amount: amountIn,
  takerTraits: TakerTraits.new({ exactIn: true }),
})
const quoted = await publicClient.call({ to: quoteTx.to, data: quoteTx.data })
assert(quoted.data, 'quote call returned no data')
const [, quotedOut] = decodeFunctionResult({ abi: ABI.SWAP_VM_ABI, functionName: 'quote', data: quoted.data })
console.log('quoted output:', quotedOut)

// 2. Approve the router to move the input token (once per token and chain).
const approveHash = await wallet.writeContract({
  address: USDC.toString(),
  abi: erc20Abi,
  functionName: 'approve',
  args: [router.toString(), amountIn],
})
await publicClient.waitForTransactionReceipt({ hash: approveHash })

// 3. Swap with a minimum-output floor and a short deadline. Balances and
// curves move between quote and fill - never submit unprotected traits.
const swapTx = SwapVMContract.buildSwapTx(router, {
  order,
  tokenIn: USDC,
  tokenOut: WETH,
  amount: amountIn,
  takerTraits: TakerTraits.new({
    exactIn: true,
    threshold: (quotedOut * 995n) / 1_000n,
    deadline: BigInt(Math.floor(Date.now() / 1_000) + 60),
  }),
})
const fillHash = await wallet.sendTransaction(swapTx)
const receipt = await publicClient.waitForTransactionReceipt({ hash: fillHash })
assert(receipt.status === 'success', 'fill reverted')

// 4. Verify the executed amounts from the router's Swapped event.
const swappedLog = receipt.logs.find((log) => log.topics[0] === SwappedEvent.TOPIC.toString())
assert(swappedLog, 'no Swapped event in the receipt')
const swapped = SwappedEvent.fromLog(swappedLog)
console.log('filled:', swapped.amountIn, '->', swapped.amountOut)

Döngüyü önce bir fork üzerinde deneyin

Yukarıdakilerin tümü yerel bir fork üzerinde güvenle prova edilir. Foundry'nin anvil'i zinciri bir blokta klonlar, böylece gerçek kontratları ve gerçek canlı pozisyonları hiçbir şeyi riske atmadan elde edersiniz. Anahtarsız gönderimler açıkken, erişim tokenını zaten tutan herhangi bir EOA gibi davranabilir ve ilk gerçek işleminizden önce keşfet, fiyatla, doldur, doğrula döngüsünün tamamını yürüyebilirsiniz.

# Real Aqua bytecode and live positions at the forked block, zero real spend
anvil --fork-url $YOUR_RPC_URL --auto-impersonate

# Point the quickstart at http://127.0.0.1:8545 and send from any EOA that
# already holds the per-chain access token - no key needed on a fork

Bir doldurma zincir üstünde nasıl yürütülür

Doldurma, SwapVM yönlendiricisine giden tek bir işlemdir. Yönlendirici pozisyonun komut programını çalıştırır: önce erişim kontrolü, sonra fiyat eğrisi, sonra token hareketleri. Aynı işlem içinde girdi tokenı EOA'nızdan LP'nin cüzdanına gider ve çıktı tokenı size döner, bu sırada Aqua kayıt defteri pozisyonun bakiyelerini güncelleyip Pushed ve Pulled yayar. Hiçbir anda hiçbir şey bir havuzda durmaz.

Her şey ya hep ya hiçtir. Yürütme sırasında herhangi bir kontrol başarısız olursa, erişim tokenı yoksa, threshold tutmadıysa, deadline geçtiyse veya cüzdan desteği yetersizse, işlemin tamamı revert olur ve hiçbir token hareket etmez. Revert olan doldurmanın maliyeti yalnızca gazdır.

Yönlendirici quote ve swap sunar ve ikisi de aynı fiyat yolunu izler. İkisi de view fonksiyonu değildir, bu yüzden quote fonksiyonunu eth_call ile statik çağırın: canlı durumu okur, verdiğiniz takası aynen fiyatlar ve hiçbir şeyi değiştirmez. Bu önizleme bir taahhüt değildir. Yürütmeyi yalnızca swap ile gönderdiğiniz traits bağlar.

TakerTraits yürütme sınırlarınızı işleme taşır. Bunları SDK değil zincir uygular. En çok kullanacaklarınız:

exactIn

Hangi tarafın sabit olduğu. Kesin girdide gönderdiğiniz miktarı sabitler, alacağınızı sınırlarsınız. Kesin çıktıda alacağınızı sabitler, göndereceğinizi sınırlarsınız.

threshold

Sınırın kendisi. Kesin girdide doldurmanın teslim etmesi gereken en düşük çıktı. Kesin çıktıda harcamanızın tavanı. Sıfır threshold kontrolü kapatır, bu yüzden onu her zaman taze bir fiyat teklifinden türetin.

deadline

Unix saniyesi cinsinden bir son tarih. Sonrasında madenciliği yapılan işlem revert olur, böylece mempoolda takılan bir doldurma bayat bir eğriye karşı yürütülemez.

customReceiver

Çıktıyı gönderen EOA yerine başka bir adrese, örneğin bir hazine adresine teslim eder. Erişim kontrolü yine işlemin kaynağına göre çalışır.

shouldUnwrap

Çıktı sarılmış yerel token olduğunda sarılmış biçim yerine yerel tokenı alın.

Sonuç için kendi hesabınıza güvenmeyin. Başarılı bir makbuz isteyin, sonra yönlendiricinin Swapped olayını çözün: orderHash, maker, taker, tokenIn, tokenOut, amountIn ve amountOut. Yürütülen miktarlar bunlardır ve muhasebenizin kaydetmesi gerekenler de bunlardır.

Ele almanız gereken hata durumları

Kapatılmış pozisyon

LP bir pozisyonu her an kapatabilir ve pozisyon gidince bakiye okumaları revert olur. API'nin opened listesinde olmayan pozisyon kapalıdır, ancak sorgular arasında gerçeğin kaynağı zincir üstü revert'tür. Her doldurmadan önce yeniden kontrol edin.

Düşük cüzdan desteği

Pozisyonlar paylaşılan bir cüzdan bakiyesinden fiyat verir. Rakip bir doldurma bakiyeyi önce boşaltabilir ve teklif iyi görünse bile transferiniz revert olur. API’deki balance ve allowance alanları ön elemeye yardım eder ama gecikmeyle endekslenir. Yalnızca taze bir zincir üstü fiyat teklifi bağlayıcıdır.

Kayan fiyat

Doldurmalar geldikçe ve zaman geçtikçe fiyatlar bayatlar. Asgari çıktı tabanı ile son tarih, kötü bir doldurmayı temiz bir geri almaya çevirir.

Erişim token’ı yok

İşlem kaynağında kimlik bilgisi yoksa dApp’te oluşturulan pozisyonlar, fiyatlama mantığı çalışmadan takası geri alır.

Kanonik olmayan adresler

Yalnızca yukarıdaki iki kanonik adres Aqua’dır. Başka yere gönderilen doldurmalar canlı pozisyonları ıskalıyor. Zincir başına doğrulanacak bir şey yok, dağıtımlar her yerde aynı.

Üretimde işletme

Operatör EOA’yı yalnızca bir cüzdan değil, bir kimlik bilgisi olarak ele alın. Zincir başına erişim tokenını o tutar, bu yüzden anahtarını özel bir imzalayıcıda yalıtın, adreste yalnızca çalışma envanteri ve gaz bulundurun ve onu başka hiçbir şey için kullanmayın.

Gaz tahmini son kapınız olsun. Cüzdan kütüphaneleri yayından önce gaz tahmin eder ve başarısız bir tahmin, bir şey gönderilmeden önce erkenden yüzeye çıkan revert’tür. Bunu atlanmış bir doldurma sayın ve körlemesine yeniden denemek yerine sonraki adaya geçin.

Üç sinyali izleyin. Keşif verisi bayatladığında veya boyut desteğe fazla yaklaştığında yükselen revert oranınız. Her doldurmanın arkasındaki fiyat teklifinin yaşı, saniyelerde kalmalı. Ve Swapped’tan gelen yürütülen miktarların teklif ettiklerinizle karşılaştırılması, sapmayı size pahalıya patlamadan yakalar.

Üretimde pozisyon keşfi

Canlı kümeye iki yoldan ulaşırsınız. En hızlı başlangıç Aqua API. Olaylardan yeniden kurmak trustless olup dış bağımlılık eklemez. İkisi de aynı fiyat teklifi ve doldurma akışını besler.

Aqua API, tüm LP'lerin şu anda açık olan bütün pozisyonlarını listeler: api.1inch.com/aqua üzerinde GET /v1.0/strategies/opened, sayfa başına 500'e kadar imleç sayfalaması ve zincir ile app filtreleriyle. Her öğe Order.decode'a vereceğiniz strategyBytes'ı, ayrıca adayları ön elemeden geçirmek için token başına balance ve allowance değerlerini içerir. İstekler diğer 1inch API'leriyle aynı API anahtarını gerektirir ve Business portal üzerinden verilir. Endeks zinciri hafif gecikmeyle izler, bu yüzden doldurmadan önce daima zincir üstünde taze fiyat teklifi alın.

Protokolün çekirdek sözleşmesi olan Aqua kayıt defteri, bir pozisyon açıldığında Shipped, kapandığında Docked olayı yayar. Canlı set, her zincirin dağıtım bloğundan itibaren loglardan yeniden kurulan Shipped eksi Docked’tır. Olay alanları topics’te değil log verisindedir: sözleşme adresi ve olay imzasına göre filtreleyin, sonra istemci tarafında çözümleyip eşleştirin.

Olay biçimleri küçüktür. Shipped, maker, app, strategyHash ve stratejinin tam baytlarını taşır. Docked, maker, app ve strategyHash taşır. SDK ikisi için de tipli yardımcılar sunar, ShippedEvent ve DockedEvent, fromLog çözücüleri ve TOPIC sabitleriyle, yani ABI'yi asla elle yazmazsınız.

import { DockedEvent, ShippedEvent } from '@1inch/aqua-sdk'
import { createPublicClient, http } from 'viem'
import { mainnet } from 'viem/chains'

const AQUA = '0x1111113ccf1426a8e30e2bff5e005d929bf6a90a'
const publicClient = createPublicClient({ chain: mainnet, transport: http() })

// Shipped and Docked carry every field in the log data, none in topics, so
// pull the registry's logs and match on the event signature client-side.
const logs = await publicClient.getLogs({
  address: AQUA,
  fromBlock: 23_000_000n, // the per-chain deployment block, or your last checkpoint
  toBlock: 'latest',
})

const live = new Map<string, ShippedEvent>()
for (const log of logs) {
  if (log.topics[0] === ShippedEvent.TOPIC.toString()) {
    const shipped = ShippedEvent.fromLog(log)
    live.set(shipped.strategyHash.toString(), shipped)
  } else if (log.topics[0] === DockedEvent.TOPIC.toString()) {
    live.delete(DockedEvent.fromLog(log).strategyHash.toString())
  }
}

// live now maps strategyHash -> Shipped payload: maker, app and the strategy
// bytes you decode with Order.decode before quoting.
console.log('open positions:', live.size)

Zincir üstü okumalar gerisini verir. Kayıt defterinin rawBalances ve safeBalances görünümleri bir pozisyonun arkasındaki cüzdan desteğini bildirir, yönlendiricinin Swapped olayları yürütülen takasları taşır. Fiyat tekliflerini önbelleğe almak yerine taze tutun.

Doldurma boyutu fiyat teklifinden değil destekten başlar. Pozisyonun desteğini kayıt defteri görünümleriyle okuyun, boyutunuzu bunun epey içinde tutun, sonra göndermeden hemen önce tam o boyut için taze bir fiyat teklifi alın. API’nin balance ve allowance alanları çok aday üzerinde ucuz bir ilk elektir, tek aday için gerçek görünümler ve fiyat teklifidir.

Çözücü SSS