Merge pull request #120 from manishdait/issue-97

feat: Added TokenClient API

Author: hendrikebbers

hiero-enterprise-base/src/main/java/com/openelements/hiero/base/TokenClient.java

@@ -116,7 +116,7 @@ public void transferNfts(@NonNull final TokenId tokenId, @NonNull final List<Lon
             @NonNull final PrivateKey fromAccountKey, @NonNull final AccountId toAccountId) throws HieroException {
         final TokenTransferRequest request = TokenTransferRequest.of(tokenId, serialNumber, fromAccountId, toAccountId,
                 fromAccountKey);
-        client.executeTransferTransactionForNft(request);
+        client.executeTransferTransaction(request);
     }
 
 

hiero-enterprise-base/src/main/java/com/openelements/hiero/base/implementation/NftClientImpl.java

@@ -430,7 +430,7 @@ public TokenBurnResult executeBurnTokenTransaction(@NonNull final TokenBurnReque
             }
 
             final TransactionReceipt receipt = executeTransactionAndWaitOnReceipt(transaction);
-            return new TokenBurnResult(receipt.transactionId, receipt.status);
+            return new TokenBurnResult(receipt.transactionId, receipt.status, receipt.totalSupply);
         } catch (final Exception e) {
             throw new HieroException("Failed to execute burn token transaction", e);
         }
@@ -452,22 +452,29 @@ public TokenMintResult executeMintTokenTransaction(@NonNull final TokenMintReque
             }
             sign(transaction, request.supplyKey());
             final TransactionReceipt receipt = executeTransactionAndWaitOnReceipt(transaction);
-            return new TokenMintResult(receipt.transactionId, receipt.status, receipt.serials);
+            return new TokenMintResult(receipt.transactionId, receipt.status, receipt.serials, receipt.totalSupply);
         } catch (final Exception e) {
             throw new HieroException("Failed to execute mint token transaction", e);
         }
     }
 
-    public TokenTransferResult executeTransferTransactionForNft(@NonNull final TokenTransferRequest request)
+    public TokenTransferResult executeTransferTransaction(@NonNull final TokenTransferRequest request)
             throws HieroException {
         Objects.requireNonNull(request, "request must not be null");
         try {
             final TransferTransaction transaction = new TransferTransaction()
                     .setMaxTransactionFee(request.maxTransactionFee())
                     .setTransactionValidDuration(request.transactionValidDuration());
-            request.serials().forEach(
-                    serial -> transaction.addNftTransfer(new NftId(request.tokenId(), serial), request.sender(),
-                            request.receiver()));
+            if (!request.serials().isEmpty()) {
+                request.serials().forEach(
+                        serial -> transaction.addNftTransfer(new NftId(request.tokenId(), serial), request.sender(),
+                                request.receiver()));
+            } else if (request.amount() != null) {
+                transaction.addTokenTransfer(request.tokenId(), request.sender(), request.amount() * -1);
+                transaction.addTokenTransfer(request.tokenId(), request.receiver(), request.amount());
+            } else {
+                throw new IllegalArgumentException("either amount or serial must be provided");
+            }
             sign(transaction, request.senderKey());
             final TransactionReceipt receipt = executeTransactionAndWaitOnReceipt(transaction);
             return new TokenTransferResult(receipt.transactionId, receipt.status);

hiero-enterprise-base/src/main/java/com/openelements/hiero/base/implementation/ProtocolLayerClientImpl.java

@@ -0,0 +1,95 @@
+package com.openelements.hiero.base.implementation;
+
+import com.openelements.hiero.base.TokenClient;
+import com.hedera.hashgraph.sdk.AccountId;
+import com.hedera.hashgraph.sdk.PrivateKey;
+import com.hedera.hashgraph.sdk.TokenId;
+import com.hedera.hashgraph.sdk.TokenType;
+import com.openelements.hiero.base.HieroException;
+import com.openelements.hiero.base.data.Account;
+import com.openelements.hiero.base.protocol.*;
+import org.jspecify.annotations.NonNull;
+
+import java.util.Objects;
+
+public class TokenClientImpl implements TokenClient {
+    private final ProtocolLayerClient client;
+
+    private final Account operationalAccount;
+
+    public TokenClientImpl(@NonNull final ProtocolLayerClient client, @NonNull final Account operationalAccount) {
+        this.client = Objects.requireNonNull(client, "client must not be null");
+        this.operationalAccount = Objects.requireNonNull(operationalAccount, "operationalAccount must not be null");
+    }
+
+    @Override
+    public TokenId createToken(@NonNull String name, @NonNull String symbol)
+            throws HieroException {
+        return createToken(name, symbol, operationalAccount);
+    }
+
+    @Override
+    public TokenId createToken(@NonNull String name, @NonNull String symbol, @NonNull PrivateKey supplyKey)
+            throws HieroException {
+        return createToken(name, symbol, operationalAccount, supplyKey);
+    }
+
+    @Override
+    public TokenId createToken(@NonNull String name, @NonNull String symbol, @NonNull AccountId treasuryAccountId,
+                               @NonNull PrivateKey treasuryKey) throws HieroException {
+        return createToken(name, symbol, treasuryAccountId, treasuryKey, operationalAccount.privateKey());
+    }
+
+    @Override
+    public TokenId createToken(@NonNull String name, @NonNull String symbol, @NonNull AccountId treasuryAccountId,
+                               @NonNull PrivateKey treasuryKey, @NonNull PrivateKey supplyKey) throws HieroException {
+        final TokenCreateRequest request = TokenCreateRequest.of(name, symbol, treasuryAccountId, treasuryKey,
+                TokenType.FUNGIBLE_COMMON, supplyKey);
+        final TokenCreateResult result = client.executeTokenCreateTransaction(request);
+        return  result.tokenId();
+    }
+
+    @Override
+    public void associateToken(@NonNull TokenId tokenId, @NonNull AccountId accountId, @NonNull PrivateKey accountKey)
+            throws HieroException {
+        final TokenAssociateRequest request = TokenAssociateRequest.of(tokenId, accountId, accountKey);
+        client.executeTokenAssociateTransaction(request);
+    }
+
+    @Override
+    public long mintToken(@NonNull TokenId tokenId, long amount) throws HieroException {
+        return mintToken(tokenId, operationalAccount.privateKey(), amount);
+    }
+
+    @Override
+    public long mintToken(@NonNull TokenId tokenId, @NonNull PrivateKey supplyKey, long amount)
+            throws HieroException {
+        final TokenMintRequest request = TokenMintRequest.of(tokenId, supplyKey, amount);
+        final TokenMintResult result = client.executeMintTokenTransaction(request);
+        return result.totalSupply();
+    }
+
+    @Override
+    public long burnToken(@NonNull TokenId tokenId, long amount) throws HieroException {
+        return burnToken(tokenId, amount, operationalAccount.privateKey());
+    }
+
+    @Override
+    public long burnToken(@NonNull TokenId tokenId, long amount, @NonNull PrivateKey supplyKey) throws HieroException {
+        final TokenBurnRequest request = TokenBurnRequest.of(tokenId, supplyKey, amount);
+        final TokenBurnResult result = client.executeBurnTokenTransaction(request);
+        return result.totalSupply();
+    }
+
+    @Override
+    public void transferToken(@NonNull TokenId tokenId, @NonNull AccountId toAccountId, long amount) throws HieroException {
+        transferToken(tokenId, operationalAccount, toAccountId, amount);
+    }
+
+    @Override
+    public void transferToken(@NonNull TokenId tokenId, @NonNull AccountId fromAccountId,
+                              @NonNull PrivateKey fromAccountKey, @NonNull AccountId toAccountId, long amount) throws HieroException {
+        final TokenTransferRequest request = TokenTransferRequest.of(tokenId, fromAccountId, toAccountId, fromAccountKey, amount);
+        client.executeTransferTransaction(request);
+    }
+}

hiero-enterprise-base/src/main/java/com/openelements/hiero/base/implementation/TokenClientImpl.java

@@ -179,7 +179,7 @@ TokenAssociateResult executeTokenAssociateTransaction(@NonNull final TokenAssoci
      * @throws HieroException if the transaction could not be executed
      */
     @NonNull
-    TokenTransferResult executeTransferTransactionForNft(@NonNull final TokenTransferRequest request)
+    TokenTransferResult executeTransferTransaction(@NonNull final TokenTransferRequest request)
             throws HieroException;
 
     /**

hiero-enterprise-base/src/main/java/com/openelements/hiero/base/protocol/ProtocolLayerClient.java

@@ -31,4 +31,9 @@ public static TokenBurnRequest of(TokenId tokenId, Set<Long> serials, PrivateKey
         return new TokenBurnRequest(TransactionRequest.DEFAULT_MAX_TRANSACTION_FEE,
                 TransactionRequest.DEFAULT_TRANSACTION_VALID_DURATION, tokenId, supplyKey, null, serials);
     }
+
+    public static TokenBurnRequest of(TokenId tokenId, PrivateKey supplyKey, long amount) {
+        return new TokenBurnRequest(TransactionRequest.DEFAULT_MAX_TRANSACTION_FEE,
+                TransactionRequest.DEFAULT_TRANSACTION_VALID_DURATION, tokenId, supplyKey, amount, null);
+    }
 }

hiero-enterprise-base/src/main/java/com/openelements/hiero/base/protocol/TokenBurnRequest.java

@@ -5,11 +5,12 @@
 import java.util.Objects;
 import org.jspecify.annotations.NonNull;
 
-public record TokenBurnResult(@NonNull TransactionId transactionId, @NonNull Status status) implements
-        TransactionResult {
+public record TokenBurnResult(@NonNull TransactionId transactionId, @NonNull Status status, @NonNull Long totalSupply)
+        implements TransactionResult {
 
     public TokenBurnResult {
         Objects.requireNonNull(transactionId, "transactionId must not be null");
         Objects.requireNonNull(status, "status must not be null");
+        Objects.requireNonNull(totalSupply, "totalSupply must not be null");
     }
 }

hiero-enterprise-base/src/main/java/com/openelements/hiero/base/protocol/TokenBurnResult.java

@@ -7,11 +7,12 @@
 import org.jspecify.annotations.NonNull;
 
 public record TokenMintResult(@NonNull TransactionId transactionId, @NonNull Status status,
-                              @NonNull List<Long> serials) implements TransactionResult {
+                              @NonNull List<Long> serials, @NonNull Long totalSupply) implements TransactionResult {
 
     public TokenMintResult {
         Objects.requireNonNull(transactionId, "transactionId must not be null");
         Objects.requireNonNull(status, "status must not be null");
         Objects.requireNonNull(serials, "serials must not be null");
+        Objects.requireNonNull(totalSupply, "totalSupply must not be null");
     }
 }

hiero-enterprise-base/src/main/java/com/openelements/hiero/base/protocol/TokenMintResult.java

@@ -8,11 +8,13 @@
 import java.util.List;
 import java.util.Objects;
 import org.jspecify.annotations.NonNull;
+import org.jspecify.annotations.Nullable;
 
 public record TokenTransferRequest(@NonNull Hbar maxTransactionFee,
                                    @NonNull Duration transactionValidDuration,
                                    @NonNull TokenId tokenId,
                                    @NonNull List<Long> serials,
+                                   @Nullable Long amount,
                                    @NonNull AccountId sender,
                                    @NonNull AccountId receiver,
                                    @NonNull PrivateKey senderKey) implements TransactionRequest {
@@ -25,9 +27,10 @@ public record TokenTransferRequest(@NonNull Hbar maxTransactionFee,
         Objects.requireNonNull(receiver, "receiver must not be null");
         Objects.requireNonNull(senderKey, "senderKey must not be null");
         Objects.requireNonNull(serials, "serials must not be null");
-        if (serials.isEmpty()) {
-            throw new IllegalArgumentException("serials must not be empty");
+        if (amount == null && serials.isEmpty()) {
+            throw new IllegalArgumentException("either amount or serial must be provided");
         }
+
         serials.forEach(serial -> {
             if (serial < 0) {
                 throw new IllegalArgumentException("serial must be positive");
@@ -43,8 +46,12 @@ public static TokenTransferRequest of(@NonNull final TokenId tokenId, final long
     public static TokenTransferRequest of(@NonNull final TokenId tokenId, @NonNull final List<Long> serials,
             @NonNull final AccountId sender, @NonNull final AccountId receiver, @NonNull final PrivateKey senderKey) {
         return new TokenTransferRequest(TransactionRequest.DEFAULT_MAX_TRANSACTION_FEE,
-                TransactionRequest.DEFAULT_TRANSACTION_VALID_DURATION, tokenId, serials, sender, receiver, senderKey);
+                TransactionRequest.DEFAULT_TRANSACTION_VALID_DURATION, tokenId, serials, null, sender, receiver, senderKey);
     }
 
-
+    public static TokenTransferRequest of(@NonNull final TokenId tokenId, @NonNull final AccountId sender,
+                                          @NonNull final AccountId receiver, @NonNull final PrivateKey senderKey, @NonNull final Long amount) {
+        return new TokenTransferRequest(TransactionRequest.DEFAULT_MAX_TRANSACTION_FEE,
+                TransactionRequest.DEFAULT_TRANSACTION_VALID_DURATION, tokenId, List.of(), amount, sender, receiver, senderKey);
+    }
 }

hiero-enterprise-base/src/main/java/com/openelements/hiero/base/protocol/TokenTransferRequest.java

@@ -55,6 +55,6 @@ void testNullParams() {
         Assertions.assertThrows(NullPointerException.class, () -> client.executeTokenCreateTransaction(null));
         Assertions.assertThrows(NullPointerException.class, () -> client.executeBurnTokenTransaction(null));
         Assertions.assertThrows(NullPointerException.class, () -> client.executeMintTokenTransaction(null));
-        Assertions.assertThrows(NullPointerException.class, () -> client.executeTransferTransactionForNft(null));
+        Assertions.assertThrows(NullPointerException.class, () -> client.executeTransferTransaction(null));
     }
 }