Skip to content
Meshline
SDK 1.6.0 · TypeView source on GitHub

Developer guide · API index

Members on this page

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

System.String

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

AccountRoute

AccountManager.State Property

The currently known account establishment state.

public Meshline.Components.AccountState State { get; }

Property Value

AccountState

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;

Event Type

System.EventHandler