入門指南
新增功能
在 caver-java 1.5.0 中,我們採用了通用架構。 通用架構是 kaia 開發環境的新軟件架構,所有 kaia SDK(caver-js/caver-java)均可共享。 它專為簡化開發體驗而設計,易於擴展到其他編程語言。
隨著 caver-java 升級到 1.5.0,除了某些 API 之外,1.4.0 中使用的 API 將被棄用。
caver-java 1.5.0 中新提供的應用程序接口如下。
caver.account
caver.account 是一個用於更新 Kaia 賬戶的賬戶密鑰(AccountKey)的軟件包,賬戶密鑰可以是一個或多個公鑰(AccountKeyPublic、AccountKeyWeightedMultiSig 和 AccountKeyRoleBased),也可以是一種特殊類型的密鑰(AccountKeyLegacy 和 AccountKeyFail)。
- 在 caver-java 1.4.0 中,
caver.account
取代了caver.tx.account
。
caver.wallet
caver.wallet 是一個管理內存錢包中 Keyring 實例的軟件包。 密鑰環是存儲 Kaia 賬戶地址及其私人密鑰的實例,該賬戶地址用於簽署交易。 caver.wallet 接受所有類型的 Keyring(單 Keyring、多 Keyring 和基於角色的 Keyring),並通過 kaia 賬戶地址進行管理。
- 在 caver-java 1.4.0 中,"caver.wallet "取代了 "caver.crypto"。
- 在 caver-java 1.4.0 中,"caver.wallet.KeyStore "取代了 "caver.wallet.WalletFile"。
caver.transaction
caver.transaction是一個提供[Transaction](.../../../learn/transactions/transactions.md#transactions-overview)相關功能的軟件包。
- 在 caver-java 1.4.0 中,"caver.transaction "取代了 "caver.tx
caver.rpc
caver.rpc 是一個提供與 kaia Node 的 rpc 調用相關功能的軟件包。
- caver.rpc.klay "和 "caver.rpc.net "分別替換了 caver-java 1.4.0 中的 "Klay "和 "Net "接口
caver.util
caver.utils 提供實用功能。
caver.contract
caver.contract "是一個軟件包,它能讓你在 kaia 中輕鬆處理智能合約。 通過 caver.contract,您可以部署智能合約,並通過調用其函數來執行它們。 caver.contract "首先從ABI(Application Binary Interface)轉換智能合約函數和事件,調用這些函數,並獲取事件信息。
先決條件
添加存儲庫
在使用 IPFS 之前,應添加一個庫存儲庫。 請先添加以下存儲庫。
maven
<repositories> <repository> <id>jitpack.io</id> <url>https://jitpack.io</url> </repository></repositories>
gradle
allprojects { repositories { ... maven { url 'https://jitpack.io' } }}
添加依賴項
maven
<dependency> <groupId>com.klaytn.caver</groupId> <artifactId>core</artifactId> <version>1.5.0</version></dependency>
gradle
implementation 'com.klaytn.caver:core:1.5.0'
如果要使用 Android 依賴關係,只需在版本字符串末尾添加 -android。 \例如 1.0.1-android)
如果想查看 JSON-RPC 請求和響應的詳細信息,請在項目中加入 LOGBack 依賴關係。 下面是一個 Gradle 構建文件示例。 您也可以將依賴關係添加到 Maven 中。 由於 caver-java 使用 SLF4J 日誌界面,因此您可以切換到自己喜歡的日誌框架,而不是 LOGBack。
implementation "ch.qos.logback:logback-classic:1.2.3"
注意:在中央資源庫中,RC、Android 和 Java 版本被列在一起。 如果使用通配符獲取版本,則可能使用了不適合自己平臺的版本。
命令行工具
該命令行工具允許你從命令行生成 Solidity 智能合約函數包裝器。
安裝 (Homebrew)
安裝需要 Java 1.8 以上版本。
$ brew tap klaytn/klaytn$ brew install caver-java
安裝完成後,您可以運行 "caver-java "命令,如下所示:
$ caver-java solidity generate -b<smart-contract>.bin -a<smart-contract>.abi -o<outputPath> -p<packagePath>
安裝 (其他)
目前,我們不支持其他軟件包管理器。 作為另一種解決方案,我們在下文中提供了一種構建 CLI 的方法。
-
下載或 fork caver-java。
-
使用 Gradle 在控制檯模塊中執行任務 "shadowDistZip"。 結果會生成
console/build/distributions/console-shadow-{version}.zip
。$ ./gradlew :console:shadowDistZip -
解壓縮構建目錄中的壓縮文件
$ unzip ./console/build/distributions/console-shadow-{version}.zip -
執行二進制文件,運行命令行工具,如下所示。 MacOS 用戶可以找到 shell 腳本文件,Window 用戶可以找到批處理文件。
$ ./console/build/distributions/console-shadow-{version}/bin/caver-java
發送 KAIA 一覽
本節介紹一個使用 "keystore 文件 "發送 KAIA 和價值轉移交易的簡單示例。 密鑰存儲文件可從 Kaia Wallet 導出。 如果您需要 KAIA 進行測試,可以從 Kaia 水龍頭 獲取測試 KAIA。
開發時,最好使用與任何真實資金都不相關的賬戶。 好的方法是創建一個新的瀏覽器配置文件(在 Chrome、Brave、Firefox 等瀏覽器上),並在該瀏覽器上安裝 Kaia 錢包,而且永遠不要向該錢包匯款。
public void sendingKLAY() throws IOException, CipherException, TransactionException { Caver caver = new Caver(Caver.KAIROS_TESTNET_URL); //Read keystore json file. File file = new File("./keystore.json"); //Decrypt keystore. ObjectMapper objectMapper = ObjectMapperFactory.getObjectMapper(); KeyStore keyStore = objectMapper.readValue(file, KeyStore.class); AbstractKeyring keyring = caver.wallet.keyring.decrypt(keyStore, "password"); //Add to caver wallet. caver.wallet.add(keyring); BigInteger value = new BigInteger(caver.utils.convertToPeb(BigDecimal.ONE, "KLAY")); //Create a value transfer transaction ValueTransfer valueTransfer = caver.transaction.valueTransfer.create( TxPropertyBuilder.valueTransfer() .setFrom(keyring.getAddress()) .setTo("0x8084fed6b1847448c24692470fc3b2ed87f9eb47") .setValue(value) .setGas(BigInteger.valueOf(25000)) ); //Sign to the transaction valueTransfer.sign(keyring); //Send a transaction to the kaia blockchain platform (kaia) Bytes32 result = caver.rpc.klay.sendRawTransaction(valueTransfer.getRawTransaction()).send(); if(result.hasError()) { throw new RuntimeException(result.getError().getMessage()); } //Check transaction receipt. TransactionReceiptProcessor transactionReceiptProcessor = new PollingTransactionReceiptProcessor(caver, 1000, 15); TransactionReceipt.TransactionReceiptData transactionReceipt = transactionReceiptProcessor.waitForTransactionReceipt(result.getResult()); }
從 caver-java 開始
連接 kaia 節點
如果運行的是 EN,可以通過更改主機和端口將其連接到自己的節點,如下所示:
Caver caver = new Caver("http://your.en.url:8551/");
管理 Keyrings
Keyring "是一個包含 kaia 賬戶地址和私人密鑰的結構。
根據所存儲密鑰的類型,"Keyring "可分為三種類型:單鑰環 "用於存儲一個地址和一個私人密鑰,"多鑰環 "用於存儲一個地址和多個私人密鑰,"基於角色的鑰環 "用於存儲一個地址和每個角色的一個或多個私人密鑰。
SingleKeyring
內部定義了 key
屬性,該 key
存儲一個私人密鑰。
MultipleKeyring
內部定義了 keys
屬性,該 keys
以數組形式實現,用於存儲多個私鑰。
RoleBasedKeyring
中定義的 keys
屬性是以 List 對象的形式實現的,其元素是 3 個私鑰數組(空 keys
看起來像"[[], [], [] ]"),因此它可以包含每個 "角色 "的多個密鑰。 數組的第一個元素填入用於 roleTransactionKey
的私鑰,第二個元素填入用於 roleAccountUpdateKey
的私鑰,第三個元素填入用於 roleFeePayerKey
的私鑰。
創建 Keyring
生成 SingleKeyring
如下圖所示,您可以隨機生成一個 keyring。
SingleKeyring keyring = caver.wallet.keyring.generate();
從私人密鑰創建 SingleKeyring
此外,如果你擁有特定的私人密鑰,還可以用它創建一個keyring,如下圖所示。
String privateKey = "0x{private key in hex}";SingleKeyring keyring = caver.wallet.keyring.createFromPrivateKey(privateKey);
使用私鑰和地址創建 SingleKeyring
如果 kaia 賬戶的私鑰與地址不相關聯,則可以使用給定的地址和私鑰創建一個密鑰環,如下所示。
String address = "0x{address in hex}";String privateKey = "0x{private key in hex}";SingleKeyring keyring = caver.wallet.keyring.createWithSingleKey(address, privateKey);
此外,您還可以從 kaia 錢包密鑰派生 SingleKeyring 實例。
String klaytnWalletKey = "0x{private key}0x{type}0x{address in hex}";SingleKeyring keyring = caver.wallet.keyring.createFromKlaytnWalletKey(klaytnWalletKey);
創建具有多個私人密鑰的 MultipleKeyring
如果要使用多個私鑰,可以使用一個地址和多個私鑰創建一個 "MultipleKeyring"。 下面的示例展示瞭如何創建具有多個私鑰的 "多重鑰匙環"。
String address = "0x{address in hex}";String[] privateKeyArray = new String[] {"0x{private key#1}", "0x{private key#2}", "0x{private key#3}"};MultipleKeyring multipleKeyring = caver.wallet.keyring.createWithMultipleKey(address, privateKeyArray);
創建帶有私鑰的 RoleBasedKeyring
要為每個 "角色 "使用不同的私鑰,需要使用 "caver.wallet.keyring.createWithRoleBasedKey"。 每個數組元素代表一個在 RoleBasedKeyring
中描述的角色。 下面的示例展示瞭如何根據每個角色的不同密鑰創建一個 RoleBasedKeyring
實例。
String address = "0x{address in hex}";String[][] privateKeyArr = new String[][] { //roleTransactionKey { "0x{privateKey in hex}", "0x{privateKey in hex}", "0x{privateKey in hex}", }, //roleAccountUpdateKey { "0x{privateKey in hex}", "0x{privateKey in hex}", "0x{privateKey in hex}", }, //roleFeePayerKey { "0x{privateKey in hex}", "0x{privateKey in hex}", "0x{privateKey in hex}", },};RoleBasedKeyring keyring = caver.wallet.keyring.createWithRoleBasedKey(address, Arrays.asList(privateKeyArr));
從 keystore json 字符串向 caver-java 添加 Keyrings。
您可以將 keyring 添加到 caver-java 提供的內存錢包中,從而更方便地使用 keyring。 以下示例說明了如何使用 Kaia Wallet 生成的密鑰存儲 JSON 文件字符串向 caver.wallet
添加密鑰。
Caver caver = new Caver(Caver.MAINNET_URL);String password = "password";String keyStoreJsonString = "{\n" + " \"version\": 4,\n" + " \"id\": \"9c12de05-0153-41c7-a8b7-849472eb5de7\",\n" + " \"address\": \"0xc02cec4d0346bf4124deeb55c5216a4138a40a8c\",\n" + " \"keyring\": [\n" + " {\n" + " \"ciphertext\": \"eacf496cea5e80eca291251b3743bf93cdbcf7072efc3a74efeaf518e2796b15\",\n" + " \"cipherparams\": {\n" + " \"iv\": \"d688a4319342e872cefcf51aef3ec2da\"\n" + " },\n" + " \"cipher\": \"aes-128-ctr\",\n" + " \"kdf\": \"scrypt\",\n" + " \"kdfparams\": {\n" + " \"dklen\": 32,\n" + " \"salt\": \"c3cee502c7157e0faa42386c6d666116ffcdf093c345166c502e23bc34e6ba40\",\n" + " \"n\": 4096,\n" + " \"r\": 8,\n" + " \"p\": 1\n" + " },\n" + " \"mac\": \"4b49574f3d3356fa0d04f73e07d5a2a6bbfdd185bedfa31f37f347bc98f2ef26\"\n" + " }\n" + " ]\n" + "}";SingleKeyring decrypt = (SingleKeyring)caver.wallet.keyring.decrypt(keyStoreJsonString, password);System.out.println("Decrypted address : " + decrypt.getAddress());System.out.println("Decrypted key : " + decrypt.getKey().getPrivateKey());SingleKeyring addedKeyring = (SingleKeyring)caver.wallet.add(decrypt);System.out.println("address : " + addedKeyring.getAddress());System.out.println("key : " + addedKeyring.getKey().getPrivateKey());
解密地址 : 0xc02cec4d0346bf4124deeb55c5216a4138a40a8c解密密鑰 : 0x93c90135ae69669e416ba5997d9274f8c8bd60748761fc421e415602d68a13a5地址 :0xc02cec4d0346bf4124deeb55c5216a4138a40a8ckey : 0x93c90135ae69669e416ba5997d9274f8c8bd60748761fc421e415602d68a13a5
從上面的輸出結果來看,將密鑰添加到 caver.wallet
後,就可以從 caver.wallet
中查詢密鑰。
如果您有需要使用的地址和私鑰,可以通過 caver.wallet.newKeyring 輕鬆創建一個密鑰環,並將其直接添加到 caver.wallet 中。
Caver caver = new Caver(Caver.MAINNET_URL);// Add to wallet with an address and a private keyAbstractKeyring addedSingleKeyring = caver.wallet.newKeyring("0x{address in hex}", "0x{private key1}");// Add to wallet with an address and private keysString[] privateKeyArr = new String[] { "0x{privateKey in hex}", "0x{privateKey in hex}", "0x{privateKey in hex}",};AbstractKeyring addedMultipleKeyring = caver.wallet.newKeyring('0x{address in hex}', privateKeyArr);// Add to wallet with an address and private keys defined by each rolesString[][] privateKeyArr = new String[][] { //roleTransactionKey { "0x{privateKey in hex}", "0x{privateKey in hex}", "0x{privateKey in hex}", }, //roleAccountUpdateKey { "0x{privateKey in hex}", "0x{privateKey in hex}", "0x{privateKey in hex}", }, //roleFeePayerKey { "0x{privateKey in hex}", "0x{privateKey in hex}", "0x{privateKey in hex}", },};AbstractKeyring addedRoleBased = caver.wallet.newKeyring('0x{address in hex}', Arrays.asList(privateKeyArr))
當使用私鑰執行 caver.wallet.newKeyring
時,一個帶有私鑰的 Keyring 實例就會創建並添加到 caver.wallet
中。 對於多個私鑰,會創建一個包含多個私鑰的 Keyring 實例並添加到 caver.wallet
。 當傳遞包含每個角色的一個或多個私鑰的 2D 字符串數組作為元素時,就會創建一個包含每個角色的不同私鑰的 Keyring 實例,並將其添加到 caver.wallet
。
caver.wallet.add
或 caver.wallet.newKeyring
返回一個添加到 caver.wallet
的 Keyring 實例。
發送交易
本節將向您介紹如何在 Kairos Testnet 上使用 caver-java 發送 KAIA。
通過 Kairos 龍頭獲取 KAIA
如果您需要 KAIA 進行測試,可以從 Kaia Wallet 獲取 Kairos testnet KAIA。 使用私鑰或密鑰存儲文件登錄 kaia 錢包,並通過龍頭接收 Kairos testnet KAIA 進行測試。