Νέες Επιλογές Διαμόρφωσης (Beta)

Αυτές οι επιλογές διαμόρφωσης είναι διαθέσιμες ξεκινώντας από το v2.2.0-beta.1. Προσθέστε τις στο υπάρχον kora.toml μαζί με τη σταθερή διαμόρφωση.

Πρόσθετα Συναλλαγών

Η ενότητα [kora.plugins] διαμορφώνει τα πρόσθετα συναλλαγών που εκτελούνται κατά τη διάρκεια των ροών υπογραφής. Τα πρόσθετα επικυρώνουν τη δομή και το περιεχόμενο των συναλλαγών πριν το Kora τις υπογράψει. Εκτελούνται για signTransaction, signAndSendTransaction, signBundle και signAndSendBundle — αλλά όχι για estimateBundleFee.

[kora.plugins]
enabled = ["gas_swap"]

Πρόσθετο gas_swap

Το πρόσθετο gas_swap επιβάλλει αυστηρή δομή συναλλαγών για λειτουργίες ανταλλαγής token-για-SOL χωρίς χρεώσεις gas. Όταν είναι ενεργοποιημένο, κάθε συναλλαγή που υποβάλλεται μέσω ροών υπογραφής πρέπει να περιέχει ακριβώς:

1. Μία μεταφορά SPL Token (SPL Token ή Token-2022) — από ιδιοκτήτη που δεν είναι πληρωτής χρεώσεων
2. Μία μεταφορά System SOL (Transfer ή TransferWithSeed) — από τον πληρωτή χρεώσεων

Οι οδηγίες Compute Budget (ορισμός ορίου/τιμής μονάδων υπολογισμού) επιτρέπονται παράλληλα με τις δύο απαιτούμενες οδηγίες. Οποιεσδήποτε πρόσθετες ή μη συναλλακτικές εξωτερικές οδηγίες απορρίπτονται.

Απαιτήσεις Διαμόρφωσης

Το πρόσθετο gas_swap επικυρώνει τη διαμόρφωσή σας κατά την εκκίνηση και θα εμφανίσει σφάλμα εάν οι απαιτήσεις δεν πληρούνται:

• Το System Program πρέπει να βρίσκεται στο allowed_programs
• Τουλάχιστον ένα πρόγραμμα token (SPL Token ή Token-2022) πρέπει να βρίσκεται στο allowed_programs
• Τουλάχιστον ένα token πρέπει να βρίσκεται στο allowed_tokens
• Το μοντέλο τιμολόγησης δεν πρέπει να είναι Free — ορίστε περιθώριο ή σταθερή τιμή

[kora.plugins]
enabled = ["gas_swap"]

[validation]
allowed_programs = [
    "11111111111111111111111111111111",              # System Program
    "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA",  # SPL Token Program
    "TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb",  # Token-2022 Program
]
allowed_tokens = [
    "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v", # USDC
]

[validation.price]
type = "margin"
margin = 0.0

Προειδοποίηση: Όταν χρησιμοποιείτε το gas_swap με σταθερή τιμολόγηση, βεβαιωθείτε ότι η σταθερή χρέωση token αξίζει τουλάχιστον max_allowed_lamports σε SOL για να αποφύγετε κατάσταση εξάντλησης όπου το SOL που αποστέλλεται υπερβαίνει το token που λαμβάνεται.

Διαμόρφωση Δέσμης

Η ενότητα INLINE_CODE_PLACEHOLDER_78b835d294b52f52_END ενεργοποιεί την υποστήριξη δέσμης Jito για ατομική εκτέλεση πολλαπλών συναλλαγών:

[kora.bundle]
enabled = true

[kora.bundle.jito]
block_engine_url = "https://mainnet.block-engine.jito.wtf"

Διαμόρφωση Jito

Διαθέσιμα URL μηχανής μπλοκ Jito:

• Mainnet (δημόσιο): https://mainnet.block-engine.jito.wtf
• Mainnet (ιδιωτικό): Επικοινωνήστε με το Jito για πρόσβαση

Σημαντικό: Όταν χρησιμοποιείτε δέσμες με φιλοδωρήματα Jito που πληρώνονται από το Kora, ορίστε allow_transfer = true στο [validation.fee_payer_policy.system] για να επιτρέψετε στον υπογράφοντα να μεταφέρει SOL για το φιλοδώρημα.

Για έναν πλήρη οδηγό σχετικά με την υλοποίηση δεσμών Jito με το Kora, δείτε τον Οδηγό Δέσμης Jito.

Προστασία Πληρωτή Τελών Lighthouse

Η ενότητα [kora.lighthouse] ενεργοποιεί την προστασία πληρωτή τελών Lighthouse. Όταν είναι ενεργοποιημένη, το Kora προσθέτει οδηγίες επιβεβαίωσης υπολοίπου στις συναλλαγές, προστατεύοντας τον πληρωτή τελών από επιθέσεις εξάντλησης επαληθεύοντας ότι το υπόλοιπο του πληρωτή τελών δεν πέφτει κάτω από τα αναμενόμενα επίπεδα.

[kora.lighthouse]
enabled = true
fail_if_transaction_size_overflow = true

Πώς Λειτουργεί

Όταν το Lighthouse είναι ενεργοποιημένο, το Kora ανακτά το τρέχον υπόλοιπο του πληρωτή τελών και προσθέτει μια οδηγία επιβεβαίωσης Lighthouse που επαληθεύει ότι το υπόλοιπο δεν πέφτει κάτω από (current_balance - estimated_fee) κατά την ολοκλήρωση της συναλλαγής. Αυτό αποτρέπει κακόβουλες συναλλαγές από το να εξαντλήσουν τον πληρωτή τελών πέρα από το αναμενόμενο κόστος.

Συμβατότητα Μεθόδων

Η προστασία Lighthouse λειτουργεί μόνο με signTransaction και signBundle. ΔΕΝ λειτουργεί με signAndSendTransaction ή signAndSendBundle.

Όταν το Lighthouse προσθέτει μια εντολή επιβεβαίωσης, τροποποιεί το μήνυμα της συναλλαγής. Αυτό ακυρώνει τυχόν προϋπάρχουσες υπογραφές πελάτη. Οι ροές signAndSend* θα αποτύγχαναν επειδή:

1. Ο πελάτης υπογράφει τη συναλλαγή
2. Το Kora προσθέτει επιβεβαίωση Lighthouse (τροποποιεί το μήνυμα)
3. Η αρχική υπογραφή του πελάτη καθίσταται άκυρη
4. Το δίκτυο απορρίπτει με "αποτυχία επαλήθευσης υπογραφής"

Συνιστώμενο μοτίβο με Lighthouse:

signTransaction → client receives modified tx → client re-signs → client sends to network

Απαιτήσεις Διαμόρφωσης

Κατά την ενεργοποίηση του Lighthouse, προσθέστε το πρόγραμμα Lighthouse στο allowed_programs σας:

[validation]
allowed_programs = [
    # ... other programs ...
    "L2TExMFKdjpN9kozasaurPirfHy9P8sbXoAN1qA3S95",  # Lighthouse Program
]

Το Kora επικυρώνει αυτό κατά την εκκίνηση και θα επιστρέψει σφάλμα εάν το Lighthouse είναι ενεργοποιημένο αλλά το πρόγραμμα δεν βρίσκεται στο allowed_programs.

Σημείωση: Εάν τα signAndSendTransaction ή signAndSendBundle είναι ενεργοποιημένα παράλληλα με το Lighthouse, το Kora θα καταγράψει μια προειδοποίηση ότι αυτές οι μέθοδοι δεν θα έχουν προστασία πληρωτή τελών.

Προστασία από Bot με reCAPTCHA

Το reCAPTCHA v3 παρέχει αόρατη προστασία από bot για ευαίσθητα endpoints. Σε αντίθεση με το API Key και το HMAC που επαληθεύουν όλα τα αιτήματα, το reCAPTCHA προστατεύει μόνο συγκεκριμένες μεθόδους υψηλού κινδύνου (μέθοδοι υπογραφής από προεπιλογή).

Διαμόρφωση Διακομιστή

Προσθέστε το KORA_RECAPTCHA_SECRET στις μεταβλητές περιβάλλοντός σας (έχει προτεραιότητα), ή προσθέστε ένα recaptcha_secret στο kora.toml σας:

[kora.auth]
recaptcha_secret = "your-recaptcha-v3-secret-key"
recaptcha_score_threshold = 0.5  # Optional: 0.0-1.0, default 0.5
protected_methods = ["signTransaction", "signAndSendTransaction", "signBundle", "signAndSendBundle"]  # Optional

Πώς Λειτουργεί

1. Ο πελάτης λαμβάνει ένα token reCAPTCHA από το API reCAPTCHA v3 της Google
2. Ο πελάτης συμπεριλαμβάνει το token στην κεφαλίδα x-recaptcha-token
3. Ο διακομιστής επαληθεύει το token με τη Google και ελέγχει τη βαθμολογία
4. Εάν η βαθμολογία >= όριο, το αίτημα συνεχίζεται· διαφορετικά επιστρέφει 401 Unauthorized

Το reCAPTCHA εκτελείται μετά την επιτυχή επαλήθευση API Key/HMAC (εάν έχει ρυθμιστεί). Οι μη προστατευμένες μέθοδοι παρακάμπτουν εντελώς την επαλήθευση reCAPTCHA.

Υλοποίηση Πελάτη

Χρησιμοποιώντας το Kora SDK:

const { KoraClient } = require("@solana/kora");

const kora = new KoraClient({
  rpcUrl: "http://localhost:8080",
  apiKey: process.env.KORA_API_KEY,
  // Callback called for each request - return fresh token
  getRecaptchaToken: async () => {
    return await grecaptcha.execute("your-site-key", { action: "sign" });
  }
});

// Token is automatically included for all requests
const result = await kora.signTransaction({ transaction: "base64..." });

Χρησιμοποιώντας fetch:

async function callKoraProtectedMethod(method, params = {}) {
  const recaptchaToken = await grecaptcha.execute("your-site-key", {
    action: "sign"
  });

  const response = await fetch("http://localhost:8080", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "x-recaptcha-token": recaptchaToken
    },
    body: JSON.stringify({
      jsonrpc: "2.0",
      method,
      params,
      id: 1
    })
  });

  return response.json();
}

Λήψη Κλειδιών reCAPTCHA

1. Μεταβείτε στην Κονσόλα Διαχείρισης Google reCAPTCHA
2. Δημιουργήστε έναν νέο ιστότοπο με reCAPTCHA v3
3. Χρησιμοποιήστε το Site Key στο frontend σας (πλευρά πελάτη)
4. Χρησιμοποιήστε το Secret Key στη ρύθμιση Kora σας (πλευρά διακομιστή)

Όρια Χρήσης

Η ενότητα [kora.usage_limit] ρυθμίζει τον περιορισμό χρήσης ανά πορτοφόλι για την αποτροπή καταχρήσεων και τη διασφάλιση δίκαιης χρήσης. Αυτό μπορεί επίσης να χρησιμοποιηθεί για τη δημιουργία προγραμμάτων ανταμοιβών που επιδοτούν τα τέλη συναλλαγών των χρηστών μέχρι ένα συγκεκριμένο όριο.

Σημείωση: Αυτή η λειτουργία απαιτεί Redis όταν είναι ενεργοποιημένη σε πολλαπλές εμφανίσεις Kora.

[kora.usage_limit]
enabled = true
cache_url = "redis://localhost:6379"
fallback_if_unavailable = true

fallback_if_unavailable

Κανόνες Ορίων Χρήσης

Η beta εκδοχή εισάγει λεπτομερείς, βασισμένους σε κανόνες περιορισμούς χρήσης. Αντί για έναν μοναδικό αριθμό max_transactions, μπορείτε να ορίσετε πολλαπλούς κανόνες που στοχεύουν συγκεκριμένους τύπους συναλλαγών ή μεμονωμένες οδηγίες, με προαιρετικά χρονικά παράθυρα.

[[kora.usage_limit.rules]]
type = "transaction"
max = 100
window_seconds = 86400  # 100 transactions per day

[[kora.usage_limit.rules]]
type = "instruction"
program = "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA"
instruction = "Transfer"
max = 50
window_seconds = 3600  # 50 SPL transfers per hour

Όταν το window_seconds έχει οριστεί, ο μετρητής επαναφέρεται μετά τη λήξη του χρονικού παραθύρου. Χωρίς αυτό, το όριο είναι μόνιμο — μόλις επιτευχθεί, το πορτοφόλι αποκλείεται μέχρι να διαγραφεί χειροκίνητα από το Redis.

Νέες Ενεργοποιημένες Μέθοδοι

Οι ακόλουθες μέθοδοι έχουν προστεθεί στο [kora.enabled_methods]:

[kora.enabled_methods]
get_version = true
estimate_bundle_fee = true
sign_bundle = false
sign_and_send_bundle = false

Δείτε τις Μεθόδους Δεσμών για την πλήρη τεκμηρίωση του API.