From 6401bece35c87bd8daa787b2b52b8852a75ae397 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Artur=20Micha=C5=82ek?= <52135326+cptartur@users.noreply.github.com> Date: Thu, 19 Jan 2023 15:31:46 +0100 Subject: [PATCH] Update docs and GatewayProvider factories (#218) --- .../provider/gateway/GatewayProvider.kt | 12 +-- .../kotlin/starknet/provider/ProviderTest.kt | 2 +- lib/starknet-jvm.md | 91 ++++++++++++++++--- 3 files changed, 83 insertions(+), 22 deletions(-) diff --git a/lib/src/main/kotlin/com/swmansion/starknet/provider/gateway/GatewayProvider.kt b/lib/src/main/kotlin/com/swmansion/starknet/provider/gateway/GatewayProvider.kt index 59264b285..60a37da0f 100644 --- a/lib/src/main/kotlin/com/swmansion/starknet/provider/gateway/GatewayProvider.kt +++ b/lib/src/main/kotlin/com/swmansion/starknet/provider/gateway/GatewayProvider.kt @@ -417,7 +417,7 @@ class GatewayProvider( companion object Factory { @JvmStatic - fun makeTestnetClient(): GatewayProvider { + fun makeTestnetProvider(): GatewayProvider { return GatewayProvider( "$TESTNET_URL/feeder_gateway", "$TESTNET_URL/gateway", @@ -426,7 +426,7 @@ class GatewayProvider( } @JvmStatic - fun makeTestnetClient(testnetId: StarknetChainId): GatewayProvider = + fun makeTestnetProvider(testnetId: StarknetChainId): GatewayProvider = when (testnetId) { StarknetChainId.TESTNET -> GatewayProvider( "$TESTNET_URL/feeder_gateway", @@ -444,7 +444,7 @@ class GatewayProvider( } @JvmStatic - fun makeTestnetClient(httpService: HttpService): GatewayProvider { + fun makeTestnetProvider(httpService: HttpService): GatewayProvider { return GatewayProvider( "$TESTNET_URL/feeder_gateway", "$TESTNET_URL/gateway", @@ -454,7 +454,7 @@ class GatewayProvider( } @JvmStatic - fun makeTestnetClient(testnetId: StarknetChainId, httpService: HttpService): GatewayProvider = + fun makeTestnetProvider(testnetId: StarknetChainId, httpService: HttpService): GatewayProvider = when (testnetId) { StarknetChainId.TESTNET -> GatewayProvider( "$TESTNET_URL/feeder_gateway", @@ -474,7 +474,7 @@ class GatewayProvider( } @JvmStatic - fun makeMainnetClient(): GatewayProvider { + fun makeMainnetProvider(): GatewayProvider { return GatewayProvider( "$MAINNET_URL/feeder_gateway", "$MAINNET_URL/gateway", @@ -483,7 +483,7 @@ class GatewayProvider( } @JvmStatic - fun makeMainnetClient(httpService: HttpService): GatewayProvider { + fun makeMainnetProvider(httpService: HttpService): GatewayProvider { return GatewayProvider( "$MAINNET_URL/feeder_gateway", "$MAINNET_URL/gateway", diff --git a/lib/src/test/kotlin/starknet/provider/ProviderTest.kt b/lib/src/test/kotlin/starknet/provider/ProviderTest.kt index 1e077f925..b76999d5e 100644 --- a/lib/src/test/kotlin/starknet/provider/ProviderTest.kt +++ b/lib/src/test/kotlin/starknet/provider/ProviderTest.kt @@ -1017,7 +1017,7 @@ class ProviderTest { """.trimIndent(), ) } - val provider = GatewayProvider.makeTestnetClient(httpService) + val provider = GatewayProvider.makeTestnetProvider(httpService) val receipt = provider.getTransactionReceipt(hash).send() as GatewayTransactionReceipt assertEquals(hash, receipt.hash) diff --git a/lib/starknet-jvm.md b/lib/starknet-jvm.md index 8602ac3b0..668d1df95 100644 --- a/lib/starknet-jvm.md +++ b/lib/starknet-jvm.md @@ -21,7 +21,7 @@ import com.swmansion.starknet.provider.gateway.GatewayProvider; public class Main { public static void main(String[] args) { // Create a provider for interacting with StarkNet - Provider provider = GatewayProvider.makeTestnetClient(); + Provider provider = GatewayProvider.makeTestnetProvider(); // Create an account interface Felt accountAddress = Felt.fromHex("0x13241455"); @@ -49,7 +49,7 @@ import com.swmansion.starknet.provider.gateway.GatewayProvider fun main() { // Create a provider for interacting with StarkNet - val provider = GatewayProvider.makeTestnetClient() + val provider = GatewayProvider.makeTestnetProvider() // Create an account interface val accountAddress = Felt.fromHex("0x1052524524") @@ -68,7 +68,7 @@ fun main() { ## Making asynchronous requests -It is also possible to make asynchronous requests. `Request.sendAsync()` returs a `CompletableFuture` +It is also possible to make asynchronous requests. `Request.sendAsync()` returns a `CompletableFuture` that can be than handled in preferred way. ### In Java @@ -87,7 +87,7 @@ import java.util.concurrent.CompletableFuture; public class Main { public static void main(String[] args) { // Create a provider for interacting with StarkNet - Provider provider = GatewayProvider.makeTestnetClient(); + Provider provider = GatewayProvider.makeTestnetProvider(); // Create an account interface Felt accountAddress = Felt.fromHex("0x13241455"); @@ -115,7 +115,7 @@ import com.swmansion.starknet.provider.gateway.GatewayProvider fun main() { // Create a provider for interacting with StarkNet - val provider = GatewayProvider.makeTestnetClient() + val provider = GatewayProvider.makeTestnetProvider() // Create an account interface val accountAddress = Felt.fromHex("0x1052524524") @@ -151,7 +151,7 @@ import java.util.List; public class Main { public static void main(String[] args) { - Provider provider = GatewayProvider.makeTestnetClient(); + Provider provider = GatewayProvider.makeTestnetProvider(); Felt address = new Felt(0x1234); Felt privateKey = new Felt(0x1); Account account = new StandardAccount(provider, address, privateKey); @@ -187,7 +187,7 @@ or in Kotlin ```kotlin fun main(args: Array) { - val provider: Provider = makeTestnetClient() + val provider: Provider = makeTestnetProvider() val address = Felt(0x1234) val privateKey = Felt(0x1) val account: Account = StandardAccount(provider, address, privateKey) @@ -221,6 +221,8 @@ fun main(args: Array) { # Package com.swmansion.starknet.crypto Cryptography and signature related classes. +This is a low level module. Recommended way of using is through +Signer and Account implementations. # Package com.swmansion.starknet.data @@ -236,21 +238,72 @@ Data classes representing StarkNet transactions. # Package com.swmansion.starknet.provider -Provider interface used for interacting with StarkNet. +Provider interface and its implementations. + +```java +// Create a provider instance +Provider provider = ... + +// Get a storage value request +Request request = provider.getStorageAt(address, key); +// Send a request +Felt response = request.send(); + +// For most methods block hash, number or tag can be specified +Request request = provider.getStorageAt(address, key, Felt.fromHex("0x123...")); +Request request = provider.getStorageAt(address, key, 1234); +Request request = provider.getStorageAt(address, key, BlockTag.LATEST); +``` # Package com.swmansion.starknet.provider.exceptions Exceptions thrown by the StarkNet providers. +`Request.send()` throws `RequestFailedException` unchecked exception. +It can optionally be handled. + +```java +Request request = ... +// Send a request +try { + Felt response = request.send(); +} catch (RequestFailedException e) { + // Handle an exception +} +``` + +In the case of `Request.sendAsync()`, an exception would have to be handled in the returned `CompletableFuture`. + # Package com.swmansion.starknet.provider.gateway Provider utilising StarkNet gateway and feeder gateway for communication with the network. +```java +// Create a provider using GatewayProvider static methods +GatewayProvider.makeTestnetProvider(); +// Chain id can be specified +GatewayProvider.makeTestnetProvider(StarknetChainId.TESTNET2); +// As well as the custom HttpService +GatewayProvider.makeTestnetProvider(myHttpService, StarknetChainId.TESTNET2); + +// Provider can be also created using a constructor +new GatewayProvider("feederGatewayUrl", "gatewayUrl", StarknetChainId.TESTNET); +// or with a custom HttpService +new GatewayProvider("feederGatewayUrl", "gatewayUrl", StarknetChainId.TESTNET, myHttpService); +``` + # Package com.swmansion.starknet.provider.rpc Provider implementing the [JSON RPC interface](https://github.com/starkware-libs/starknet-specs) to communicate with the network. +```java +// JsonRpcProvider can only be created using constructor +new JsonRpcProvider("rpcNodeUrl", StarknetChainId.TESTNET); +// or with a custom HttpService +new JsonRpcProvider("rpcNodeUrl", StarknetChainId.TESTNET, myHttpService); +``` + # Package com.swmansion.starknet.service.http Http service used to communicate with StarkNet. @@ -263,14 +316,22 @@ import com.swmansion.starknet.service.http.OkHttpService; // (...) -var httpClient = new OkHttpClient(); -var httpService = new OkHttpService(httpClient); - -var provider = GatewayProvider.makeTestnetClient(httpService); -var account1 = new StandardAccount(provider, accountAddress1, privateKey1); -var account2 = new StandardAccount(provider, accountAddress2, privateKey2); +OkHttpClient httpClient = new OkHttpClient(); +OkHttpService httpService = new OkHttpService(httpClient); ``` # Package com.swmansion.starknet.signer -Signer interface used to sign StarkNet transactions. +Signer interface and its implementations. +Recommended way of using Signer is through an Account. + +```java +// Create a signer +Signer signer = ... + +// Sign a transaction +List signature = signer.signTransaction(tx); + +// Get a public key +Felt publicKey = signer.getPublicKey(); +```