fix: subscription error codes, input validation, OnboardPlanUser guards

- Added SUBSCRIBE_FAILED, SUBSCRIPTION_NOT_FOUND, SHARE_FAILED to ErrorCodes
  with severity mapping and user messages
- Guarded ulong.Parse(subscriptionId) with TryParse in OnboardPlanUserAsync
- Changed default feeSpendLimit from 500k to 5M udvpn (5 P2P, ~125 sessions)
- Added input validation (null checks, >0 guards) to CancelSubscription,
  RenewSubscription, ShareSubscription, UpdateSubscription builders
- Added FeeGrantTests test file

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: Sentinel-Bluebuilder

src/Sentinel.SDK.Core/ChainClient.FeeGrants.cs

@@ -3,7 +3,8 @@
 namespace Sentinel.SDK.Core;
 
 /// <summary>
-/// ChainClient partial — fee grant queries, issued-grant lookups, and expiry monitoring.
+/// ChainClient partial — fee grant queries, issued-grant lookups, expiry monitoring,
+/// and operator workflow helpers (grantPlanSubscribers, renewExpiringGrants, monitorFeeGrants).
 /// </summary>
 public sealed partial class ChainClient
 {
@@ -167,4 +168,107 @@ public async Task<IReadOnlyList<ExpiringGrant>> GetExpiringGrantsAsync(
 
         return null;
     }
+
+    // ─── Operator Workflow Functions ───
+
+    /// <summary>
+    /// Build fee grant messages for all subscribers of a plan.
+    /// Queries all subscribers, filters out the granter and already-granted addresses,
+    /// and returns batch MsgGrantAllowance messages ready for broadcast.
+    /// </summary>
+    /// <param name="planId">Plan ID whose subscribers should receive grants.</param>
+    /// <param name="granterAddress">Granter address (sent1...) — plan operator who pays gas.</param>
+    /// <param name="spendLimitUdvpn">Optional spend limit per grant in udvpn.</param>
+    /// <param name="expiration">Optional expiry date for each grant.</param>
+    /// <param name="ct">Cancellation token.</param>
+    /// <returns>Array of grant messages (empty if all subscribers already have grants).</returns>
+    public async Task<SentinelMessage[]> BuildGrantPlanSubscribersAsync(
+        int planId,
+        string granterAddress,
+        long? spendLimitUdvpn = null,
+        DateTime? expiration = null,
+        CancellationToken ct = default)
+    {
+        ArgumentException.ThrowIfNullOrWhiteSpace(granterAddress);
+        if (planId <= 0)
+            throw new ArgumentOutOfRangeException(nameof(planId), "Must be > 0");
+
+        // Get all subscribers, excluding the operator
+        var subscribers = await QueryPlanSubscribersAsync(planId, excludeAddress: granterAddress, ct: ct);
+        if (subscribers.Count == 0)
+            return [];
+
+        // Get existing grants issued by this granter to filter out already-granted
+        var existingGrants = await QueryFeeGrantsIssuedAsync(granterAddress, ct);
+        var alreadyGranted = new HashSet<string>(existingGrants.Select(g => g.Grantee));
+
+        var messages = new List<SentinelMessage>();
+        foreach (var sub in subscribers)
+        {
+            if (alreadyGranted.Contains(sub.Address))
+                continue;
+
+            messages.Add(MessageBuilder.GrantFeeAllowance(
+                granterAddress, sub.Address, spendLimitUdvpn, expiration));
+        }
+
+        return messages.ToArray();
+    }
+
+    /// <summary>
+    /// Build messages to renew fee grants expiring within a given window.
+    /// For each expiring grant: revokes the old one, creates a new one with fresh expiration.
+    /// </summary>
+    /// <param name="granterAddress">Granter address (sent1...).</param>
+    /// <param name="withinDays">Days ahead to check for expiring grants (default: 7).</param>
+    /// <param name="newSpendLimitUdvpn">Optional spend limit for renewed grants.</param>
+    /// <param name="newExpiration">Optional new expiration for renewed grants.</param>
+    /// <param name="ct">Cancellation token.</param>
+    /// <returns>Array of revoke+grant message pairs (empty if nothing is expiring).</returns>
+    public async Task<SentinelMessage[]> BuildRenewExpiringGrantsAsync(
+        string granterAddress,
+        int withinDays = 7,
+        long? newSpendLimitUdvpn = null,
+        DateTime? newExpiration = null,
+        CancellationToken ct = default)
+    {
+        ArgumentException.ThrowIfNullOrWhiteSpace(granterAddress);
+
+        var expiring = await GetExpiringGrantsAsync(granterAddress, withinDays, role: "granter", ct: ct);
+        if (expiring.Count == 0)
+            return [];
+
+        var messages = new List<SentinelMessage>();
+        foreach (var grant in expiring)
+        {
+            // Revoke old grant
+            messages.Add(MessageBuilder.RevokeFeeAllowance(granterAddress, grant.Grantee));
+            // Re-grant with fresh expiration
+            messages.Add(MessageBuilder.GrantFeeAllowance(
+                granterAddress, grant.Grantee, newSpendLimitUdvpn, newExpiration));
+        }
+
+        return messages.ToArray();
+    }
+
+    /// <summary>
+    /// Find an existing active session between a wallet and a specific node.
+    /// Prevents double-allocation by checking before starting a new session.
+    /// </summary>
+    /// <param name="walletAddress">Account address (sent1...).</param>
+    /// <param name="nodeAddress">Node address (sentnode1...).</param>
+    /// <param name="ct">Cancellation token.</param>
+    /// <returns>The existing session, or null if none found.</returns>
+    public async Task<ChainSession?> FindExistingSessionAsync(
+        string walletAddress,
+        string nodeAddress,
+        CancellationToken ct = default)
+    {
+        ArgumentException.ThrowIfNullOrWhiteSpace(walletAddress);
+        ArgumentException.ThrowIfNullOrWhiteSpace(nodeAddress);
+
+        var sessions = await GetSessionsAsync(walletAddress, status: "1", ct: ct);
+        return sessions.FirstOrDefault(s =>
+            string.Equals(s.NodeAddress, nodeAddress, StringComparison.OrdinalIgnoreCase));
+    }
 }

src/Sentinel.SDK.Core/ChainClient.Queries.cs

@@ -395,6 +395,54 @@ public async Task<IReadOnlyList<ActiveSession>> QueryActiveSessionsForAddressAsy
         return null;
     }
 
+    // ─── Subscription Allocation Queries ───
+
+    /// <summary>
+    /// Query all bandwidth allocations for a subscription.
+    /// Used to verify that a user has been granted access to a plan subscription via sharing.
+    /// NOTE: Uses v2 endpoint because v3 returns 501 Not Implemented.
+    /// </summary>
+    /// <param name="subscriptionId">Subscription ID on chain.</param>
+    /// <param name="ct">Cancellation token.</param>
+    /// <returns>List of allocations for the subscription.</returns>
+    public async Task<List<SubscriptionAllocation>> QuerySubscriptionAllocationsAsync(
+        ulong subscriptionId, CancellationToken ct = default)
+    {
+        // NOTE: v3 endpoint for this specific query hasn't been implemented yet (returns 501).
+        // The v2 path works and returns the same allocation data. Same situation as /plan/v3/plans/{id}.
+        var path = $"/sentinel/subscription/v2/subscriptions/{subscriptionId}/allocations";
+        var allocations = new List<SubscriptionAllocation>();
+
+        try
+        {
+            var json = await LcdGetAsync(path, ct);
+
+            if (json.TryGetProperty("allocations", out var arr) &&
+                arr.ValueKind == JsonValueKind.Array)
+            {
+                foreach (var a in arr.EnumerateArray())
+                {
+                    var id = a.TryGetProperty("id", out var idEl)
+                        ? idEl.GetString() ?? idEl.ToString() : "0";
+                    var address = a.TryGetProperty("address", out var addrEl)
+                        ? addrEl.GetString() ?? "" : "";
+                    var granted = a.TryGetProperty("granted_bytes", out var gEl)
+                        ? gEl.GetString() ?? "0" : "0";
+                    var utilised = a.TryGetProperty("utilised_bytes", out var uEl)
+                        ? uEl.GetString() ?? "0" : "0";
+
+                    allocations.Add(new SubscriptionAllocation(id, address, granted, utilised));
+                }
+            }
+        }
+        catch (SentinelException ex) when (ex.Code == "CLIENT_HTTP_404")
+        {
+            // No allocations found — return empty list
+        }
+
+        return allocations;
+    }
+
     // ─── Additional Query Methods ───
 
     /// <summary>

src/Sentinel.SDK.Core/IChainClient.cs

@@ -168,6 +168,23 @@ public interface IChainClient
     /// <returns>List of grants expiring within the specified window.</returns>
     Task<IReadOnlyList<ExpiringGrant>> GetExpiringGrantsAsync(string address, int withinDays = 7, string role = "grantee", CancellationToken ct = default);
 
+    // ─── Operator Workflow ───
+
+    /// <summary>
+    /// Build fee grant messages for all subscribers of a plan.
+    /// </summary>
+    Task<SentinelMessage[]> BuildGrantPlanSubscribersAsync(int planId, string granterAddress, long? spendLimitUdvpn = null, DateTime? expiration = null, CancellationToken ct = default);
+
+    /// <summary>
+    /// Build messages to renew fee grants expiring within a given window.
+    /// </summary>
+    Task<SentinelMessage[]> BuildRenewExpiringGrantsAsync(string granterAddress, int withinDays = 7, long? newSpendLimitUdvpn = null, DateTime? newExpiration = null, CancellationToken ct = default);
+
+    /// <summary>
+    /// Find an existing active session between a wallet and a specific node.
+    /// </summary>
+    Task<ChainSession?> FindExistingSessionAsync(string walletAddress, string nodeAddress, CancellationToken ct = default);
+
     // ─── Provider ───
 
     /// <summary>

src/Sentinel.SDK.Core/MessageBuilder.Subscription.cs

@@ -79,6 +79,10 @@ public static SentinelMessage SubStartSession(
     /// <summary>Cancel a subscription. Proto: sentinel.subscription.v3.MsgCancelSubscriptionRequest</summary>
     public static SentinelMessage CancelSubscription(string from, ulong subscriptionId)
     {
+        ArgumentException.ThrowIfNullOrWhiteSpace(from);
+        if (subscriptionId == 0)
+            throw new ArgumentOutOfRangeException(nameof(subscriptionId), "Must be > 0");
+
         using var s = new MemoryStream();
         WriteStringField(s, 1, from);
         WriteVarintField(s, 2, subscriptionId);
@@ -88,27 +92,43 @@ public static SentinelMessage CancelSubscription(string from, ulong subscription
     /// <summary>Renew an expiring subscription. Proto: sentinel.subscription.v3.MsgRenewSubscriptionRequest</summary>
     public static SentinelMessage RenewSubscription(string from, ulong subscriptionId, string denom = "udvpn")
     {
+        ArgumentException.ThrowIfNullOrWhiteSpace(from);
+        if (subscriptionId == 0)
+            throw new ArgumentOutOfRangeException(nameof(subscriptionId), "Must be > 0");
+
         using var s = new MemoryStream();
         WriteStringField(s, 1, from);
         WriteVarintField(s, 2, subscriptionId);
         WriteStringField(s, 3, denom);
         return new SentinelMessage("/sentinel.subscription.v3.MsgRenewSubscriptionRequest", s.ToArray());
     }
 
-    /// <summary>Share bandwidth with another address. Proto: sentinel.subscription.v3.MsgShareSubscriptionRequest</summary>
+    /// <summary>Share bandwidth with another address. Proto: sentinel.subscription.v3.MsgShareSubscriptionRequest
+    /// Field 4 (bytes) is cosmossdk.io/math.Int — proto string type (wire type 2), NOT varint.</summary>
     public static SentinelMessage ShareSubscription(string from, ulong subscriptionId, string accAddress, long bytes)
     {
+        ArgumentException.ThrowIfNullOrWhiteSpace(from);
+        if (subscriptionId == 0)
+            throw new ArgumentOutOfRangeException(nameof(subscriptionId), "Must be > 0");
+        ArgumentException.ThrowIfNullOrWhiteSpace(accAddress);
+        if (bytes <= 0)
+            throw new ArgumentOutOfRangeException(nameof(bytes), "Must be > 0");
+
         using var s = new MemoryStream();
         WriteStringField(s, 1, from);
         WriteVarintField(s, 2, subscriptionId);
         WriteStringField(s, 3, accAddress);
-        WriteVarintField(s, 4, (ulong)bytes);
+        WriteStringField(s, 4, bytes.ToString());
         return new SentinelMessage("/sentinel.subscription.v3.MsgShareSubscriptionRequest", s.ToArray());
     }
 
     /// <summary>Update subscription renewal policy. Proto: sentinel.subscription.v3.MsgUpdateSubscriptionRequest</summary>
     public static SentinelMessage UpdateSubscription(string from, ulong subscriptionId, int renewalPricePolicy)
     {
+        ArgumentException.ThrowIfNullOrWhiteSpace(from);
+        if (subscriptionId == 0)
+            throw new ArgumentOutOfRangeException(nameof(subscriptionId), "Must be > 0");
+
         using var s = new MemoryStream();
         WriteStringField(s, 1, from);
         WriteVarintField(s, 2, subscriptionId);

src/Sentinel.SDK.Core/SentinelErrors.cs

@@ -159,6 +159,11 @@ public static class ErrorCodes
     public const string AlreadyConnected = "ALREADY_CONNECTED";
     public const string PartialConnectionFailed = "PARTIAL_CONNECTION_FAILED";
 
+    // ─── Subscription / Plan ───
+    public const string SubscribeFailed = "SUBSCRIBE_FAILED";
+    public const string SubscriptionNotFound = "SUBSCRIPTION_NOT_FOUND";
+    public const string ShareFailed = "SHARE_FAILED";
+
     // ─── C#-specific (extras not in JS — keep for backwards compat) ───
     public const string NotConnected = "NOT_CONNECTED";
     public const string HandshakeFailed = "HANDSHAKE_FAILED";
@@ -228,6 +233,9 @@ public static class ErrorSeverity
         ErrorCodes.PartialConnectionFailed => "recoverable",
         ErrorCodes.SessionExists => "recoverable",
         ErrorCodes.HandshakeFailed => "recoverable",
+        ErrorCodes.SubscribeFailed => "retryable",
+        ErrorCodes.SubscriptionNotFound => "retryable",
+        ErrorCodes.ShareFailed => "retryable",
 
         // Infrastructure — check system state
         ErrorCodes.TlsCertChanged => "infrastructure",
@@ -283,6 +291,9 @@ public static class ErrorSeverity
         ErrorCodes.SessionPoisoned => "Session is poisoned (previously failed). Start a new session.",
         ErrorCodes.PartialConnectionFailed => "Payment succeeded but connection failed. Use recovery to retry.",
         ErrorCodes.Aborted => "Connection was cancelled.",
+        ErrorCodes.SubscribeFailed => "Failed to subscribe to the plan. Check your balance and try again.",
+        ErrorCodes.SubscriptionNotFound => "Subscription not found after payment. Check chain state.",
+        ErrorCodes.ShareFailed => "Failed to share subscription bandwidth. Try again.",
         ErrorCodes.InvalidMnemonic => "Invalid wallet phrase. Must be 12 or 24 words.",
         ErrorCodes.InvalidNodeAddress => "Invalid node address.",
         ErrorCodes.InvalidOptions => "Invalid connection options provided.",

src/Sentinel.SDK.Core/TransactionBuilder.cs

@@ -502,6 +502,107 @@ private static byte[] BuildTxRaw(byte[] txBodyBytes, byte[] authInfoBytes, byte[
         return stream.ToArray();
     }
 
+    // ─── High-Level Subscription Operations ───
+
+    /// <summary>
+    /// Share a subscription's bandwidth with another address.
+    /// Builds and broadcasts a MsgShareSubscriptionRequest.
+    /// The bytes parameter specifies the bandwidth allowance (cosmossdk.io/math.Int).
+    /// NOTE: Only bytes-based sharing is supported — the chain has no time/duration field.
+    /// The operator must manage user expiry externally.
+    /// </summary>
+    /// <param name="subscriptionId">Subscription ID to share.</param>
+    /// <param name="recipientAddress">Address to share with (sent1...).</param>
+    /// <param name="bytes">Bytes of bandwidth to grant (e.g. 1073741824 for 1 GB).</param>
+    /// <returns>Transaction result with hash and success status.</returns>
+    public async Task<TxResult> ShareSubscriptionAsync(
+        ulong subscriptionId, string recipientAddress, long bytes)
+    {
+        ArgumentException.ThrowIfNullOrWhiteSpace(recipientAddress);
+        if (subscriptionId == 0)
+            throw new ArgumentOutOfRangeException(nameof(subscriptionId), "Must be > 0");
+        if (bytes <= 0)
+            throw new ArgumentOutOfRangeException(nameof(bytes), "Must be > 0");
+
+        var msg = MessageBuilder.ShareSubscription(
+            _wallet.Address, subscriptionId, recipientAddress, bytes);
+        return await BroadcastAsync(msg);
+    }
+
+    /// <summary>
+    /// Complete "add user to plan" flow: subscribe to plan, share bandwidth with user,
+    /// and optionally grant a fee allowance so the user doesn't pay gas.
+    /// This is the primary operation for plan operators onboarding new users.
+    /// </summary>
+    /// <param name="planId">Plan ID to subscribe to.</param>
+    /// <param name="userAddress">User address to share with (sent1...).</param>
+    /// <param name="bytes">Bytes of bandwidth to grant the user.</param>
+    /// <param name="denom">Payment denomination (default: "udvpn").</param>
+    /// <param name="grantFee">If true, also grants a fee allowance to the user.</param>
+    /// <param name="feeSpendLimit">Max fee allowance in udvpn (default: 5,000,000 = 5 P2P, enough for ~125 sessions).</param>
+    /// <param name="feeExpiration">Fee grant expiration (default: null = no expiry).</param>
+    /// <returns>Onboard result with subscription ID and all TX hashes.</returns>
+    public async Task<OnboardResult> OnboardPlanUserAsync(
+        ulong planId,
+        string userAddress,
+        long bytes,
+        string denom = "udvpn",
+        bool grantFee = false,
+        long feeSpendLimit = 5_000_000,
+        DateTime? feeExpiration = null)
+    {
+        ArgumentException.ThrowIfNullOrWhiteSpace(userAddress);
+        if (planId == 0)
+            throw new ArgumentOutOfRangeException(nameof(planId), "Must be > 0");
+        if (bytes <= 0)
+            throw new ArgumentOutOfRangeException(nameof(bytes), "Must be > 0");
+
+        // Step 1: Subscribe to plan
+        var subMsg = MessageBuilder.StartSubscription(_wallet.Address, planId, denom);
+        var subResult = await BroadcastAsync(subMsg);
+
+        if (!subResult.Success)
+            throw new SentinelException("SUBSCRIBE_FAILED",
+                $"Subscribe to plan {planId} failed: {subResult.RawLog}");
+
+        // Step 2: Query to find the subscription ID
+        await Task.Delay(5000); // Wait for chain state to propagate
+        var subs = await _client.GetSubscriptionsAsync(_wallet.Address);
+        var match = subs
+            .Where(s => s.PlanId == planId.ToString() &&
+                        s.Status.Contains("ACTIVE", StringComparison.OrdinalIgnoreCase))
+            .OrderByDescending(s => s.Id)
+            .FirstOrDefault();
+
+        var subscriptionId = match?.Id
+            ?? throw new SentinelException("SUBSCRIPTION_NOT_FOUND",
+                $"Subscription for plan {planId} not found after successful TX");
+
+        // Step 3: Share subscription with user (bytes-based)
+        if (!ulong.TryParse(subscriptionId, out var subId))
+            throw new SentinelException(ErrorCodes.SubscriptionNotFound,
+                $"Invalid subscription ID format: {subscriptionId}");
+        var shareMsg = MessageBuilder.ShareSubscription(
+            _wallet.Address, subId, userAddress, bytes);
+        var shareResult = await BroadcastAsync(shareMsg);
+
+        if (!shareResult.Success)
+            throw new SentinelException("SHARE_FAILED",
+                $"Share subscription {subscriptionId} failed: {shareResult.RawLog}");
+
+        // Step 4: Optional fee grant
+        string? grantTxHash = null;
+        if (grantFee)
+        {
+            var grantMsg = MessageBuilder.GrantFeeAllowance(
+                _wallet.Address, userAddress, feeSpendLimit, feeExpiration);
+            var grantResult = await BroadcastAsync(grantMsg);
+            grantTxHash = grantResult.TxHash;
+        }
+
+        return new OnboardResult(subscriptionId, subResult.TxHash, shareResult.TxHash, grantTxHash);
+    }
+
     // ─── Gas Estimation ───
 
     /// <summary>