Members on this page
AccountChangedAccountManager(ClientOptions, DatabaseOptions, RelayClientPool, IAccountSigner)EnsureRouteAsync(string, TimeSpan, CancellationToken)GetRouteAsync(string, CancellationToken)PublishRouteAsync(string, TimeSpan, Nullable<long>, bool, CancellationToken)RefreshRouteAsync(string, CancellationToken)AccountIdRouteState
Meshline.Sdk
Meshline.Components
AccountManager Class
Resolves and publishes signed account routes and retains the current account's known route.
public sealed class AccountManager : Meshline.Components.ClientComponent
Inheritance System.Object → ClientComponent → AccountManager
Exceptions
System.ArgumentNullException
The network context in options is null. The options argument is null.
System.ArgumentException
The configured account identifier is invalid.
System.NotSupportedException
The configured account identifier uses an unsupported account namespace.
Constructors
AccountManager(ClientOptions, DatabaseOptions, RelayClientPool, IAccountSigner) Constructor
Resolves and publishes signed account routes and retains the current account's known route.
public AccountManager(Meshline.Models.Client.ClientOptions options, Meshline.Storage.DatabaseOptions databaseOptions, Meshline.Transport.RelayClientPool relayClients, Meshline.Interactions.IAccountSigner? accountSigner=null);
Parameters
options ClientOptions
The network and account configuration for this component.
databaseOptions DatabaseOptions
The SQLite database configuration; create its parent directory and apply migrations before initialization.
relayClients RelayClientPool
The shared relay pool. The application owns it and must dispose it after all dependent components.
accountSigner IAccountSigner
The application-owned account signer required for account-authorized operations, or null when those operations are not needed.
Exceptions
System.ArgumentNullException
The network context in options is null. The options argument is null.
System.ArgumentException
The configured account identifier is invalid.
System.NotSupportedException
The configured account identifier uses an unsupported account namespace.
Properties
AccountManager.AccountId Property
The account's CAIP-10 identifier.
public string AccountId { get; }
Property Value
AccountManager.Route Property
The current account's last known route, or null when no route is known.
public Meshline.Models.Protocol.AccountRoute? Route { get; }
Property Value
AccountManager.State Property
The currently known account establishment state.
public Meshline.Components.AccountState State { get; }
Property Value
Methods
AccountManager.EnsureRouteAsync(string, TimeSpan, CancellationToken) Method
Ensures a valid route to the same home relay, reconciling unfinished publications before reporting success.
public System.Threading.Tasks.Task<Meshline.Models.Protocol.AccountRoute> EnsureRouteAsync(string relayId, System.TimeSpan validity, System.Threading.CancellationToken cancellationToken=default(System.Threading.CancellationToken));
Parameters
relayId System.String
The original or initial home relay's canonical identifier; this operation never selects another relay.
validity System.TimeSpan
The lifetime of a newly published route, from one second through 3650 days. Existing valid routes are retained; unfinished requests require their original lifetime.
cancellationToken System.Threading.CancellationToken
A token that cancels waiting or publication. Cancellation does not undo an accepted request; repeat the operation to reconcile it.
Returns
System.Threading.Tasks.Task<AccountRoute>
The verified, unexpired route after any unfinished publication has been reconciled.
Exceptions
AccountRouteException
Route authorization could not complete. The reason distinguishes signing, relay, parameter, state and unknown-submission failures.
System.ArgumentException
The relay identifier is invalid.
System.ArgumentOutOfRangeException
The validity is outside the supported range or the route revision cannot be incremented.
System.OperationCanceledException
The caller cancels or the component is disposed.
System.ObjectDisposedException
The component or a dependency has been disposed.
System.InvalidOperationException
Initialization is incomplete or no active relay is available.
Microsoft.EntityFrameworkCore.DbUpdateException
Local publication state cannot be committed.
Remarks
An unexpired verified route with no unresolved publication is reused without network I/O or signing.
Before publication, discovery must complete successfully. A missing response does not invalidate an unexpired retained route.
Unexpired unfinished submissions retain their original signed document. After discovery, an expired request can be superseded only with a retained verified route to the same relay; an initial request alone does not establish that relay's authority.
First publication requires authoritative or unexpired staged device state at the relay; use MeshlineClient.EstablishAccountAsync for complete setup.
This operation does not authorize a device, initialize a profile, migrate relays, or start synchronization.
Use one account manager per local account session; explicit publications and ensure calls share its publication gate.
AccountManager.GetRouteAsync(string, CancellationToken) Method
Returns a verified cached route, refreshing it in the background when due, or awaits discovery on a cache miss.
public System.Threading.Tasks.Task<Meshline.Models.Protocol.AccountRoute?> GetRouteAsync(string? accountId=null, System.Threading.CancellationToken cancellationToken=default(System.Threading.CancellationToken));
Parameters
accountId System.String
The target account identifier, or null for the current account.
cancellationToken System.Threading.CancellationToken
A token that can cancel the operation.
Returns
System.Threading.Tasks.Task<AccountRoute>
The verified route, or null when no route can be resolved.
Exceptions
System.OperationCanceledException
The operation is canceled through cancellationToken or the component lifetime ends. Per-relay timeouts encountered during discovery are collected as transport failures.
System.InvalidOperationException
This component or a required component has not completed initialization. No active relay is available for route discovery.
System.ObjectDisposedException
This component, a required component, or the shared relay pool has been disposed.
System.Net.Http.HttpRequestException
No attempted relay can complete route discovery; individual transient or verification failures are available in the inner aggregate exception.
RelayException
The relay rejects the operation with a structured protocol error that is not handled by this method.
System.IO.InvalidDataException
A resolved route conflicts with or predates the route already stored locally.
System.Text.Json.JsonException
A stored or received protocol document cannot be serialized or deserialized.
System.Text.DecoderFallbackException
A relay response contains bytes that are not valid UTF-8.
Microsoft.Data.Sqlite.SqliteException
The SQLite database cannot be opened or a database command fails, for example because the schema is not migrated or the file is locked.
Microsoft.EntityFrameworkCore.DbUpdateException
Persisting local changes fails, including database constraint or optimistic-concurrency failures.
System.ArgumentException
The requested account identifier is invalid.
System.NotSupportedException
The requested account uses an unsupported account namespace.
Remarks
Reads trigger a shared refresh one hour after success or one minute after failure; failures preserve unexpired routes.
Previously verified routes are reused from this account's trusted storage after checking network binding, revision and signed expiry.
Use RefreshRouteAsync(string, CancellationToken) when the operation requires a remote lookup.
AccountManager.PublishRouteAsync(string, TimeSpan, Nullable<long>, bool, CancellationToken) Method
Signs and publishes a newer home-relay route using the account signer.
public System.Threading.Tasks.Task<Meshline.Models.Protocol.AccountRoute> PublishRouteAsync(string relayId, System.TimeSpan validity, System.Nullable<long> revision=null, bool isRecovery=false, System.Threading.CancellationToken cancellationToken=default(System.Threading.CancellationToken));
Parameters
relayId System.String
The relay's canonical lowercase Neo script-hash identifier.
validity System.TimeSpan
The validity duration, from one second through 3650 days.
revision System.Nullable<System.Int64>
An explicit newer revision, or null for automatic revision selection.
isRecovery System.Boolean
Whether to select a recovery revision when no revision is supplied.
cancellationToken System.Threading.CancellationToken
A token that can cancel the operation.
Returns
System.Threading.Tasks.Task<AccountRoute>
The published route with the relay's verified signature.
Exceptions
System.OperationCanceledException
The caller cancels the operation or a component or relay lifetime ends.
System.TimeoutException
An SDK request deadline expires. Data contains operation and timeoutSeconds; InnerException preserves the cancellation cause.
System.InvalidOperationException
This component or a required component has not completed initialization. An account signer is unavailable, the relay is not active, or an unresolved publication would be replaced by different input.
System.ObjectDisposedException
This component, a required component, or the shared relay pool has been disposed.
System.Net.Http.HttpRequestException
Relay discovery, authentication, or the HTTP request fails at the transport layer.
RelayException
The relay rejects the operation with a structured protocol error that is not handled by this method.
System.IO.InvalidDataException
Relay evidence or returned state is missing, inconsistent, or fails protocol validation.
System.Text.Json.JsonException
A stored or received protocol document cannot be serialized or deserialized.
System.Text.DecoderFallbackException
A relay response contains bytes that are not valid UTF-8.
Microsoft.Data.Sqlite.SqliteException
The SQLite database cannot be opened or a database command fails, for example because the schema is not migrated or the file is locked.
Microsoft.EntityFrameworkCore.DbUpdateException
Persisting local changes fails, including database constraint or optimistic-concurrency failures.
System.Security.Cryptography.CryptographicException
The account signer produced a route whose identity or account signature is invalid, or signature verification fails.
System.ArgumentOutOfRangeException
The route validity is outside one second through 3650 days, or the selected revision is not a newer nonnegative safe integer.
System.ArgumentException
The relay identifier is invalid or the account signer belongs to another account.
AccountManager.RefreshRouteAsync(string, CancellationToken) Method
Awaits remote route discovery, bypassing cache freshness and failure cooldown while sharing an in-flight lookup for this account.
public System.Threading.Tasks.Task<Meshline.Models.Protocol.AccountRoute?> RefreshRouteAsync(string? accountId=null, System.Threading.CancellationToken cancellationToken=default(System.Threading.CancellationToken));
Parameters
accountId System.String
The target account identifier, or null for the current account.
cancellationToken System.Threading.CancellationToken
A token that can cancel the operation.
Returns
System.Threading.Tasks.Task<AccountRoute>
The verified route, or null when no route can be resolved.
Exceptions
System.OperationCanceledException
The operation is canceled through cancellationToken or the component lifetime ends. Per-relay timeouts encountered during discovery are collected as transport failures.
System.InvalidOperationException
This component or a required component has not completed initialization. No active relay is available for route discovery.
System.ObjectDisposedException
This component, a required component, or the shared relay pool has been disposed.
System.Net.Http.HttpRequestException
No attempted relay can complete route discovery; individual transient or verification failures are available in the inner aggregate exception.
RelayException
The relay rejects the operation with a structured protocol error that is not handled by this method.
System.IO.InvalidDataException
A resolved route conflicts with or predates the route already stored locally.
System.Text.Json.JsonException
A stored or received protocol document cannot be serialized or deserialized.
System.Text.DecoderFallbackException
A relay response contains bytes that are not valid UTF-8.
Microsoft.Data.Sqlite.SqliteException
The SQLite database cannot be opened or a database command fails, for example because the schema is not migrated or the file is locked.
Microsoft.EntityFrameworkCore.DbUpdateException
Persisting local changes fails, including database constraint or optimistic-concurrency failures.
System.ArgumentException
The requested account identifier is invalid.
System.NotSupportedException
The requested account uses an unsupported account namespace.
Remarks
Cancellation stops only this caller's wait. Stop or disposal cancels and drains shared refreshes.
Failures propagate to this caller and leave unexpired cached routes available to ordinary reads.
A not-found result returns null without invalidating an unexpired signed route. Concurrent newer local publication takes precedence.
Events
AccountManager.AccountChanged Event
Occurs when the current account's known route or establishment state changes.
public event EventHandler? AccountChanged;