HoloNET Client

Runnable example: examples/01-Client (connecting, installing, zome calls, signals and admin calls). Tutorials: learn.holonet.oasisomniverse.one.

The two clients

Both take an optional HoloNETDNA (the settings) and an optional logger in their constructors.

Settings: HoloNETDNA

The most used settings:

HoloNETDNAManager loads and saves these as HoloNETDNA.json if you want them in a file.

Connecting

var admin = new HoloNETClientAdmin(new HoloNETDNA { HolochainConductorMode = HolochainConductorModeEnum.UseEmbedded });
HoloNETConnectedEventArgs connected = await admin.ConnectAsync();

The one-call install. InstallEnableSignAttachAndConnectToHappAsync(appId, happPath, roleName) does every step Holochain 0.7 needs:

1. Generates an agent key and installs the app. An app that's already installed is kept, with its agent, unless you pass uninstallhAppIfAlreadyInstalled: true.
2. Enables it.
3. Creates signing credentials and an assigned zome-call grant.
4. Attaches an app interface.
5. Issues an app authentication token.
6. Returns a connected HoloNETClientAppAgent in HoloNETClientAppAgent.

Use InstallEnableSignAndAttachHappAsync if you want to connect the app client yourself.

Connecting an app client manually:

var token = await admin.IssueAppAuthenticationTokenAsync("my-app");
var client = new HoloNETClientAppAgent("my-app", agentPubKey, new HoloNETDNA
{
    AppAuthenticationToken = token.TokenIssued.token,
    AutoStartHolochainConductor = false
});
await client.ConnectAsync("my-app", "ws://localhost:" + appPort);
await client.WaitTillReadyForZomeCallsAsync();

Zome calls

ZomeFunctionCallBackEventArgs r = await client.CallZomeFunctionAsync("zome", "function", new { field = "value" });

• What you pass. paramsObject can be an anonymous object, a dictionary, a class or a primitive. It's serialised to MessagePack using its field names.
• What comes back. The decoded return value is in ZomeReturnValue and ZomeReturnData, and the record hash in ZomeReturnHash. Records holds decoded Holochain records. Pass entryDataObjectTypeReturnedFromZome to have entries mapped onto your type.
• Errors. IsError and Message tell you if the conductor or your zome returned an error. Calls never throw for zome errors.
• Callbacks and ids. Overloads take a callback and/or a request id so you can match responses yourself. ConductorResponseCallBackMode.UseCallBackEvents fires OnZomeFunctionCallBack instead of waiting.

Signals

• Emitted signals. When your zome calls emit_signal, client.OnSignalCallBack fires. e.RawSignalData.Data holds the raw MessagePack bytes, and the decoded forms are on the event args.
• Remote signals between agents. These use send_remote_signal and recv_remote_signal in your zome. The OASIS hApp's hypernet_* functions are a ready-made example: HyperNET and HoloNET API signals are built on them.
• Direct signals between apps. GrantDirectSignalCapabilityAsync and SendDirectSignalAsync send these.

The admin API

All of these have Async and sync versions:

The app API

Events

Every request also raises an event when its response arrives, for example OnAppInstalledCallBack, OnZomeFunctionCallBack and OnSignalCallBack. There are also lifecycle events: OnConnected, OnDisconnected, OnError, OnReadyForZomeCalls, OnHolochainConductorStarting, OnHolochainConductorStarted, OnDataSent and OnDataReceived. The README has the complete list.

Shutting down

await client.DisconnectAsync();
await admin.ShutdownHoloNETAsync(); // disconnects and stops the conductor HoloNET started (if AutoShutdownHolochainConductor)

Threading and sync calls

• Thread safety. Request ids are allocated atomically, so one client can be used from several threads.
• Sync calls inside events. The sync wrappers (CallZomeFunction, InstallApp, ...) are safe to call from inside HoloNET's own event handlers: HoloNET detects this and avoids deadlocking.
• UI apps. HoloNET's receive loop runs off the UI thread. Marshal back to the UI thread yourself in WPF, WinForms or Unity.

Unity

Use the netstandard2.1 build from the same NuGet packages. The HoloUnity notes are in the main README.