feat: implement staking

Scripts/generate-api/generate-api-models-config.json

@@ -17,6 +17,8 @@
   },
   "typeMappings": {
     "number": "kotlin.Int",
+    "double": "kotlin.Double",
+    "float": "kotlin.Double",
     "integer": "kotlin.Int",
     "int64": "kotlin.Long",
     "int32": "kotlin.Int",

Scripts/generate-api/generate-api-models.sh

@@ -83,6 +83,19 @@ def _rewrite_refs(node):
 data = _rewrite_refs(data)
 schemas = components_schemas
 
+# Stamp format: "double" on properties that carry floating-point values so the
+# Kotlin generator maps them to kotlin.Double instead of the default kotlin.Int.
+FLOAT_PROPERTIES = {
+    "StakingQuote": {"apy"},
+    "StakingProviderInfo": {"apy"},
+}
+for schema_name, prop_names in FLOAT_PROPERTIES.items():
+    schema = schemas.get(schema_name, {})
+    for prop_name in prop_names:
+        prop = (schema.get("properties") or {}).get(prop_name)
+        if isinstance(prop, dict) and prop.get("type") == "number":
+            prop["format"] = "double"
+
 def add_discriminated_union(name, discriminator, cases, description=None):
     mapped_cases = []
     for case in cases:

TONWalletKit-Android/api/src/main/java/io/ton/walletkit/ITONStakingManager.kt

@@ -0,0 +1,123 @@
+/*
+ * Copyright (c) 2025 TonTech
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+package io.ton.walletkit
+
+import io.ton.walletkit.api.generated.TONNetwork
+import io.ton.walletkit.api.generated.TONStakeParams
+import io.ton.walletkit.api.generated.TONStakingBalance
+import io.ton.walletkit.api.generated.TONStakingProviderInfo
+import io.ton.walletkit.api.generated.TONStakingQuote
+import io.ton.walletkit.api.generated.TONStakingQuoteParams
+import io.ton.walletkit.api.generated.TONTransactionRequest
+import io.ton.walletkit.api.generated.TONUnstakeMode
+import io.ton.walletkit.model.TONUserFriendlyAddress
+import kotlinx.serialization.json.JsonElement
+
+/**
+ * Manages staking providers and exposes staking operations.
+ */
+interface ITONStakingManager {
+
+    /**
+     * Register a staking provider created via [ITONWalletKit.tonStakersStakingProvider].
+     */
+    suspend fun register(provider: ITONTonStakersStakingProvider)
+
+    /**
+     * Set the default provider used when no providerId is passed to query methods.
+     *
+     * @param providerId The [ITONTonStakersStakingProvider.identifier] of the provider to use by default
+     */
+    fun setDefaultProvider(providerId: TONStakingProviderIdentifier)
+
+    /**
+     * Get a stake or unstake quote.
+     *
+     * @param params Quote parameters including direction, amount, and optional fields
+     * @param providerId Override which provider to use (uses default when null)
+     * @return Staking quote with input/output amounts and metadata
+     */
+    suspend fun getQuote(
+        params: TONStakingQuoteParams<JsonElement>,
+        providerId: TONStakingProviderIdentifier? = null,
+    ): TONStakingQuote
+
+    /**
+     * Build a stake or unstake transaction from a previously obtained quote.
+     *
+     * The returned [TONTransactionRequest] can be passed to [ITONWallet.send].
+     *
+     * @param params Stake parameters including the quote and user address
+     * @param providerId Override which provider to use (uses default when null)
+     * @return Transaction request ready for [ITONWallet.send] or [ITONWallet.preview]
+     */
+    suspend fun buildStakeTransaction(
+        params: TONStakeParams<JsonElement>,
+        providerId: TONStakingProviderIdentifier? = null,
+    ): TONTransactionRequest
+
+    /**
+     * Get the user's staked balance.
+     *
+     * @param userAddress User's wallet address
+     * @param network TON network (uses current network when null)
+     * @param providerId Override which provider to use (uses default when null)
+     * @return Staking balance including staked amount and instant-unstake availability
+     */
+    suspend fun getStakedBalance(
+        userAddress: TONUserFriendlyAddress,
+        network: TONNetwork? = null,
+        providerId: TONStakingProviderIdentifier? = null,
+    ): TONStakingBalance
+
+    /**
+     * Get general information about a staking provider (APY, instant-unstake liquidity).
+     *
+     * @param network TON network (uses current network when null)
+     * @param providerId Override which provider to use (uses default when null)
+     * @return Provider info including APY as a percentage value
+     */
+    suspend fun getStakingProviderInfo(
+        network: TONNetwork? = null,
+        providerId: TONStakingProviderIdentifier? = null,
+    ): TONStakingProviderInfo
+
+    /**
+     * Get the unstake modes supported by a staking provider.
+     *
+     * @param providerId Override which provider to use (uses default when null)
+     * @return List of supported unstake modes
+     */
+    suspend fun getSupportedUnstakeModes(
+        providerId: TONStakingProviderIdentifier? = null,
+    ): List<TONUnstakeMode>
+}
+
+/**
+ * Represents a registered TonStakers staking provider.
+ *
+ * Created via [ITONWalletKit.tonStakersStakingProvider] and registered with [ITONStakingManager.register].
+ */
+interface ITONTonStakersStakingProvider {
+    /** Typed staking provider identifier recognised by [ITONStakingManager]. */
+    val identifier: TONTonStakersStakingProviderIdentifier
+}

TONWalletKit-Android/api/src/main/java/io/ton/walletkit/ITONWalletKit.kt

@@ -23,6 +23,7 @@ package io.ton.walletkit
 
 import android.content.Context
 import io.ton.walletkit.api.MAINNET
+import io.ton.walletkit.api.TONTonStakersProviderConfig
 import io.ton.walletkit.api.generated.TONNetwork
 import io.ton.walletkit.api.generated.TONSignatureDomain
 import io.ton.walletkit.config.TONWalletKitConfiguration
@@ -164,6 +165,25 @@ interface ITONWalletKit {
      * Create WebView TON Connect injector.
      */
     fun createWebViewInjector(webView: android.webkit.WebView, walletId: String? = null): WebViewTonConnectInjector
+
+    // ── Staking ──
+
+    /**
+     * Access the staking manager for registering providers and performing staking operations.
+     */
+    fun staking(): ITONStakingManager
+
+    /**
+     * Create a TonStakers staking provider.
+     *
+     * Call [ITONStakingManager.register] with the returned provider to make it available for quotes.
+     *
+     * @param config Optional per-chain configuration (contract address, TonAPI key)
+     * @return A provider that can be registered with [staking]
+     */
+    suspend fun tonStakersStakingProvider(
+        config: TONTonStakersProviderConfig? = null,
+    ): ITONTonStakersStakingProvider
 }
 
 interface WebViewTonConnectInjector {

TONWalletKit-Android/api/src/main/java/io/ton/walletkit/TONProviderIdentifier.kt

@@ -0,0 +1,52 @@
+/*
+ * Copyright (c) 2025 TonTech
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+package io.ton.walletkit
+
+/**
+ * Typed provider identifier used by public SDK APIs instead of raw strings.
+ */
+interface TONProviderIdentifier {
+    val name: String
+}
+
+/**
+ * Type-erased provider identifier.
+ */
+data class AnyTONProviderIdentifier(
+    override val name: String,
+) : TONProviderIdentifier
+
+/**
+ * Marker interface for staking provider identifiers.
+ */
+interface TONStakingProviderIdentifier : TONProviderIdentifier
+
+/**
+ * Identifier for the TonStakers staking provider.
+ */
+data class TONTonStakersStakingProviderIdentifier(
+    override val name: String = DEFAULT_NAME,
+) : TONStakingProviderIdentifier {
+    companion object {
+        const val DEFAULT_NAME = "tonstakers"
+    }
+}

TONWalletKit-Android/api/src/main/java/io/ton/walletkit/api/TONTonStakersProviderConfig.kt

@@ -0,0 +1,41 @@
+/*
+ * Copyright (c) 2025 TonTech
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+package io.ton.walletkit.api
+
+import io.ton.walletkit.api.generated.TONTonStakersChainConfig
+
+/**
+ * Per-chain configuration for the TonStakers staking provider.
+ *
+ * The underlying JS API uses an index-signature type `{ [chainId: string]: TonStakersChainConfig }`
+ * where chainIds are "-239" (mainnet) and "-3" (testnet). This class provides a named-field
+ * alternative that converts to the required map via [toChainConfigMap].
+ */
+data class TONTonStakersProviderConfig(
+    val mainnet: TONTonStakersChainConfig? = null,
+    val testnet: TONTonStakersChainConfig? = null,
+) {
+    fun toChainConfigMap(): Map<String, TONTonStakersChainConfig> = buildMap {
+        mainnet?.let { put("-239", it) }
+        testnet?.let { put("-3", it) }
+    }
+}

TONWalletKit-Android/api/src/main/java/io/ton/walletkit/api/generated/TONAccountState.kt

@@ -34,8 +34,8 @@ import kotlinx.serialization.Serializable
 /**
  * State of an account at a specific point in time.
  *
- * @param hash The state hash of the account
  * @param balance
+ * @param hash The state hash of the account
  * @param extraCurrencies Map of extra currency IDs to their amounts. Extra currencies are additional tokens that can be attached to TON messages.
  * @param accountStatus
  * @param frozenHash The hash of the frozen account state, if the account is frozen
@@ -45,13 +45,13 @@ import kotlinx.serialization.Serializable
 @Serializable
 data class TONAccountState(
 
-    /* The state hash of the account */
-    @SerialName(value = "hash")
-    val hash: kotlin.String,
-
     @SerialName(value = "balance")
     val balance: kotlin.String,
 
+    /* The state hash of the account */
+    @SerialName(value = "hash")
+    val hash: kotlin.String? = null,
+
     /* Map of extra currency IDs to their amounts. Extra currencies are additional tokens that can be attached to TON messages. */
     @SerialName(value = "extraCurrencies")
     val extraCurrencies: kotlin.collections.Map<kotlin.String, kotlin.String>? = null,

TONWalletKit-Android/api/src/main/java/io/ton/walletkit/api/generated/TONStakeParams.kt

@@ -0,0 +1,52 @@
+/*
+ * Copyright (c) 2025 TonTech
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+@file:Suppress(
+    "ArrayInDataClass",
+    "EnumEntryName",
+    "RemoveRedundantQualifierName",
+    "UnusedImport",
+)
+
+package io.ton.walletkit.api.generated
+
+import io.ton.walletkit.model.TONUserFriendlyAddress
+import kotlinx.serialization.SerialName
+import kotlinx.serialization.Serializable
+
+/**
+ *
+ *
+ * @param quote
+ * @param userAddress
+ * @param providerOptions Provider-specific options
+ */
+@Serializable
+data class TONStakeParams<TProviderOptions>(
+    @SerialName("quote")
+    val quote: TONStakingQuote,
+    @SerialName("userAddress")
+    val userAddress: io.ton.walletkit.model.TONUserFriendlyAddress,
+    @SerialName("providerOptions")
+    val providerOptions: TProviderOptions? = null,
+) {
+    companion object
+}