TonUtils added (with AddressUtils, CoinUtils, TextUtils)

Author: justdmitry

TonLibDotNet.Tests/Utils/AddressUtilsTests.cs

@@ -0,0 +1,15 @@
+namespace TonLibDotNet.Utils
+{
+    public class AddressUtilsTests
+    {
+        [Theory]
+        [InlineData("EQBYTuYbLf8INxFtD8tQeNk5ZLy-nAX9ahQbG_yl1qQ-GEMS", true, "EQBYTuYbLf8INxFtD8tQeNk5ZLy-nAX9ahQbG_yl1qQ-GEMS")]
+        [InlineData("EQBYTuYbLf8INxFtD8tQeNk5ZLy-nAX9ahQbG_yl1qQ-GEMS", false, "UQBYTuYbLf8INxFtD8tQeNk5ZLy-nAX9ahQbG_yl1qQ-GB7X")]
+        [InlineData("UQBYTuYbLf8INxFtD8tQeNk5ZLy-nAX9ahQbG_yl1qQ-GB7X", false, "UQBYTuYbLf8INxFtD8tQeNk5ZLy-nAX9ahQbG_yl1qQ-GB7X")]
+        [InlineData("UQBYTuYbLf8INxFtD8tQeNk5ZLy-nAX9ahQbG_yl1qQ-GB7X", true, "EQBYTuYbLf8INxFtD8tQeNk5ZLy-nAX9ahQbG_yl1qQ-GEMS")]
+        public void SetBounceableOk(string source, bool flag, string expected)
+        {
+            Assert.Equal(expected, AddressUtils.Instance.SetBounceable(source, flag));
+        }
+    }
+}

TonLibDotNet.Tests/Utils/TextUtilsTexts.cs

@@ -0,0 +1,52 @@
+namespace TonLibDotNet.Utils
+{
+    public class TextUtilsTexts
+    {
+        [Theory]
+        [InlineData("Hello, World!", "SGVsbG8sIFdvcmxkIQ==")]
+        public void EncodeAsBase64(string source, string encoded)
+        {
+            Assert.Equal(encoded, TextUtils.Instance.EncodeAsBase64(source));
+        }
+
+        [Fact]
+        public void EncodeAsBase64ForEmpty()
+        {
+            Assert.Equal(string.Empty, TextUtils.Instance.EncodeAsBase64(string.Empty));
+        }
+
+        [Fact]
+        public void EncodeAsBase64ForNull()
+        {
+            Assert.Null(TextUtils.Instance.EncodeAsBase64(null));
+        }
+
+        [Theory]
+        [InlineData("SGVsbG8sIFdvcmxkIQ==", true, "Hello, World!")]
+        [InlineData("SGVsbG8s\r\nIFdvcmxkIQ==", true, "Hello, World!")]
+        [InlineData("SGVsbG8sIFdvcmxkIQ===", false, "")]
+        [InlineData("SGVsbG8sIFdvcmxkIQ=", false, "")]
+        [InlineData("Hello, World!", false, "")]
+        public void TryDecodeBase64(string source, bool success, string decoded)
+        {
+            Assert.Equal(success, TextUtils.Instance.TryDecodeBase64(source, out var value));
+
+            if (success)
+            {
+                Assert.Equal(decoded, value);
+            }
+        }
+
+        [Fact]
+        public void TryDecodeBase64ForEmpty()
+        {
+            Assert.False(TextUtils.Instance.TryDecodeBase64(string.Empty, out _));
+        }
+
+        [Fact]
+        public void TryDecodeBase64ForNull()
+        {
+            Assert.False(TextUtils.Instance.TryDecodeBase64(null, out _));
+        }
+    }
+}

TonLibDotNet/ITonClient.cs

@@ -15,13 +15,17 @@ public interface ITonClient
         Task<TResponse> Execute<TResponse>(RequestBase<TResponse> request)
             where TResponse : TypeBase;
 
+        [Obsolete("Use TonUtils.Coins.FromNano()")]
         decimal ConvertFromNanoTon(long nano);
 
+        [Obsolete("Use TonUtils.Coins.ToNano()")]
         long ConvertToNanoTon(decimal ton);
 
+        [Obsolete("Use TonUtils.Text.EncodeAsBase64")]
         [return: NotNullIfNotNull("source")]
         string? EncodeStringAsBase64(string? source);
 
+        [Obsolete("Use TonUtils.Text.TryDecodeBase64")]
         bool TryDecodeBase64AsString(string? source, [NotNullWhen(true)] out string? result);
     }
 }

TonLibDotNet/TonClient.cs

@@ -168,43 +168,23 @@ public async Task<TResponse> Execute<TResponse>(RequestBase<TResponse> request)
 
         public decimal ConvertFromNanoTon(long nano)
         {
-            // Last division - to get rid of trailing zeroes, see https://stackoverflow.com/questions/4525854/remove-trailing-zeros
-            return nano * 0.000_000_001M / 1.000000000000000000000000000000000m;
+            return TonUtils.Coins.FromNano(nano);
         }
 
         public long ConvertToNanoTon(decimal ton)
         {
-            return Convert.ToInt64(ton * 1_000_000_000M);
+            return TonUtils.Coins.ToNano(ton);
         }
 
         [return: NotNullIfNotNull("source")]
         public string? EncodeStringAsBase64(string? source)
         {
-            if (string.IsNullOrEmpty(source))
-            {
-                return source;
-            }
-
-            return Convert.ToBase64String(System.Text.Encoding.UTF8.GetBytes(source));
+            return TonUtils.Text.EncodeAsBase64(source);
         }
 
         public bool TryDecodeBase64AsString(string? source, [NotNullWhen(true)] out string? result)
         {
-            if (string.IsNullOrEmpty(source))
-            {
-                result = null;
-                return false;
-            }
-
-            var bytes = new byte[source.Length];
-            if (!Convert.TryFromBase64String(source, bytes, out var count))
-            {
-                result = null;
-                return false;
-            }
-
-            result = System.Text.Encoding.UTF8.GetString(bytes.AsSpan()[..count]);
-            return true;
+            return TonUtils.Text.TryDecodeBase64(source, out result);
         }
 
         public void Dispose()

TonLibDotNet/TonUtils.cs

@@ -0,0 +1,23 @@
+using System.Diagnostics.CodeAnalysis;
+using TonLibDotNet.Utils;
+
+namespace TonLibDotNet
+{
+    public static class TonUtils
+    {
+        /// <summary>
+        /// Useful function to work with coin amounts.
+        /// </summary>
+        public static CoinUtils Coins { get; } = CoinUtils.Instance;
+
+        /// <summary>
+        /// Useful function to work with addresses.
+        /// </summary>
+        public static AddressUtils Address { get; } = AddressUtils.Instance;
+
+        /// <summary>
+        /// Useful function to work with text strings.
+        /// </summary>
+        public static TextUtils Text { get; } = TextUtils.Instance;
+    }
+}

TonLibDotNet/Utils/AddressUtils.cs

@@ -0,0 +1,44 @@
+using System.Diagnostics.CodeAnalysis;
+
+namespace TonLibDotNet.Utils
+{
+    public class AddressUtils
+    {
+        public static readonly AddressUtils Instance = new ();
+
+        public const byte BasechainId = AddressValidator.BasechainId;
+        public const byte MasterchainId = AddressValidator.MasterchainId;
+
+        /// <summary>
+        /// Checks if provided 'address' is valid (including checksum check), return
+        /// </summary>
+        /// <param name="address">Address to check.</param>
+        /// <param name="workchainId">After successful validation contains 'Workchain ID' of address (compare with <see cref="BasechainId"/> or <see cref="MasterchainId"/>).</param>
+        /// <param name="bounceable">After successful validation contains 'Bounceable' flag of address.</param>
+        /// <param name="testnetOnly">After successful validation contains 'TestnetOnly' flag of address.</param>
+        /// <returns>Returns <b>true</b> if address is valid, and <b>false</b> otherwise.</returns>
+        /// <exception cref="ArgumentNullException">When 'address' is null or empty string.</exception>
+        public bool IsValid([NotNullWhen(true)] string address, out byte workchainId, out bool bounceable, out bool testnetOnly)
+        {
+            return AddressValidator.TryParseAddress(address, out workchainId, out _, out bounceable, out testnetOnly, out _);
+        }
+
+        /// <summary>
+        /// Updates address (if needed): sets 'bounceable' flag to required value.
+        /// </summary>
+        /// <param name="address">Address to convert.</param>
+        /// <param name="bounceable">Required value of 'bounceable' flag.</param>
+        /// <returns>Returns updated address (with flag changed). Returns original one when flag has already been equal to required value.</returns>
+        /// <exception cref="ArgumentException">When 'address' is not valid (<see cref="IsValid"/>).</exception>
+        /// <exception cref="ArgumentNullException">When 'address' is null or empty string.</exception>
+        public string SetBounceable(string address, bool bounceable)
+        {
+            if (!AddressValidator.TryParseAddress(address, out var workchainId, out var accountId, out var bounceableOld, out var testnetOnly, out var urlSafe))
+            {
+                throw new ArgumentException("Invalid address", nameof(address));
+            }
+
+            return bounceable == bounceableOld ? address : AddressValidator.MakeAddress(workchainId, accountId, bounceable, testnetOnly, urlSafe);
+        }
+    }
+}

TonLibDotNet/Utils/CoinUtils.cs

@@ -0,0 +1,26 @@
+namespace TonLibDotNet.Utils
+{
+    public class CoinUtils
+    {
+        public static readonly CoinUtils Instance = new ();
+
+        /// <summary>
+        /// Converts nano-TON amount to decimal TON (moves decimal point to 9 positions to the left).
+        /// </summary>
+        /// <remarks>It's safe to store nano-TON as 'long' while total TON supply is unchanged (5*10^18), details are in <see href="https://t.me/tondev/122940"/>.</remarks>
+        public decimal FromNano(long nano)
+        {
+            // Last division is to get rid of trailing zeroes, see https://stackoverflow.com/questions/4525854/remove-trailing-zeros
+            return nano * 0.000_000_001M / 1.000000000000000000000000000000000m;
+        }
+
+        /// <summary>
+        /// Converts decimal TON amount to nano-TONs (moves decimal point to 9 positions to the right).
+        /// </summary>
+        /// <remarks>It's safe to store nano-TON as 'long' while total TON supply is unchanged (5*10^18), details are in <see href="https://t.me/tondev/122940"/>.</remarks>
+        public long ToNano(decimal ton)
+        {
+            return Convert.ToInt64(ton * 1_000_000_000M);
+        }
+    }
+}

TonLibDotNet/Utils/TextUtils.cs

@@ -0,0 +1,51 @@
+using System.Diagnostics.CodeAnalysis;
+
+namespace TonLibDotNet.Utils
+{
+    public class TextUtils
+    {
+        public static readonly TextUtils Instance = new ();
+
+        /// <summary>
+        /// Encodes string for transaction comment (which usually stored in Base64).
+        /// </summary>
+        /// <param name="source">Source string (to encode).</param>
+        /// <returns>Encoded string.</returns>
+        /// <remarks>Returns null or empty string when 'source' is null or empty string, respectively.</remarks>
+        [return: NotNullIfNotNull("source")]
+        public string? EncodeAsBase64(string? source)
+        {
+            if (string.IsNullOrEmpty(source))
+            {
+                return source;
+            }
+
+            return Convert.ToBase64String(System.Text.Encoding.UTF8.GetBytes(source));
+        }
+
+        /// <summary>
+        /// Tries to decode string from Base64 (transaction comments usually stored in Base64).
+        /// </summary>
+        /// <param name="source">Source string (to decode).</param>
+        /// <param name="result">Decoded string.</param>
+        /// <remarks>Returns <b>false</b> when 'source' is null, empty string or invalid/incomplete Base64 string.</remarks>
+        public bool TryDecodeBase64(string? source, [NotNullWhen(true)] out string? result)
+        {
+            if (string.IsNullOrEmpty(source))
+            {
+                result = null;
+                return false;
+            }
+
+            Span<byte> bytes = stackalloc byte[source.Length];
+            if (!Convert.TryFromBase64String(source, bytes, out var count))
+            {
+                result = null;
+                return false;
+            }
+
+            result = System.Text.Encoding.UTF8.GetString(bytes[..count]);
+            return true;
+        }
+    }
+}