EdjCase.ICP.Agent 2.0.0-beta.25

ICP.NET

Collection of Internet Computer Protocol (ICP) libraries for .NET/Blazor

• Agent

  • Library to communicate to and from the Internet Computer
  • Nuget: EdjCase.ICP.Agent

• Candid

  • Library of Candid Encoding, Models and Helpers
  • Nuget: EdjCase.ICP.Candid

• Client Generator

  • Library of generating C# client code from *.did files
  • Nuget: EdjCase.ICP.ClientGenerator

• Internet Identity (Experimental)

  • Library of Internet Identity integration. Allowing computers to sign FIDO2/WebAuthn flows to login to Internet Identity
  • EXPERIMENTAL: Windows only for now and there are security implications
  • Nuget: EdjCase.ICP.InternetIdentity

• Samples

  • A few projects to demo the capabilities of the ICP libraries
    • Blazor
    • AspNetCore
    • CLI

Agent

Usage (Manual)

• Dont define any types and use CandidValue and CandidType
• Call functions using Candid objects

// Create http agent with anonymous identity
IAgent agent = new HttpAgent();

// Create Candid arg to send in request
ulong proposalId = 1234;
CandidArg arg = CandidArg.FromCandid(
	CandidTypedValue.Nat64(proposalId) // Candid type with no conversion
);

// Make request to IC
string method = "get_proposal_info";
Principal governanceCanisterId = Principal.FromText("rrkah-fqaaa-aaaaa-aaaaq-cai");
QueryResponse response = await agent.QueryAsync(governanceCanisterId, method, arg);

CandidArg reply = response.ThrowOrGetReply();
// Convert to custom class
OptionalValue<ProposalInfo> info = reply.Arg.ToObjects<OptionalValue<ProposalInfo>>();

Usage (Self Defined Types)

• Declare types of api models
• Call functions and use custom object converters

// Create http agent with anonymous identity
IAgent agent = new HttpAgent();

// Create Candid arg to send in request
ulong proposalId = 1234;
CandidArg arg = CandidArg.FromCandid(
    CandidTypedValue.FromObject(proposalId) // Conversion can be C# or custom types
);

// Make request to IC
string method = "get_proposal_info";
Principal governanceCanisterId = Principal.FromText("rrkah-fqaaa-aaaaa-aaaaq-cai");
QueryResponse response = await agent.QueryAsync(governanceCanisterId, method, arg);

CandidArg reply = response.ThrowOrGetReply();
// Convert to custom class
OptionalValue<ProposalInfo> info = reply.Arg.ToObjects<OptionalValue<ProposalInfo>>(); // Conversion to custom or C# types

Usage (w/ Client Generator)

• Run Client Generator on *.did file (see Client Generator below)
• Use generated client and models to call function

// Create http agent with anonymous identity
IAgent agent = new HttpAgent();

// Create new instance of client generated by `Client Generator` (this is using Governance.did for the NNS)
var client = new GovernanceApiClient(agent, Principal.FromText("rrkah-fqaaa-aaaaa-aaaaq-cai"));

// Make request
OptionalValue<ProposalInfo> info = await client.GetProposalInfoAsync(62143);

Candid

Parse from bytes

CandidArg arg = CandidArg.FromBytes(rawCandidBytes);

Reading candid values directly

CandidArg arg = CandidArg.FromBytes(rawCandidBytes);
CandidValue firstArg = arg.Values[0];
string title = firstArg.AsRecord()["title"];

Converting candid to and from custom classes

// Deserialize
CandidArg arg = CandidArg.FromBytes(rawCandidBytes);
(MyObj1 obj, MyObj2 obj2) = arg.ToObjects<MyObj1, MyObj2>();

// Serialze
MyObj obj = new MyObj
{
    Title = "Title 1",
    IsGoodTitle = false
};
CandidTypedValue value = CandidTypedValue.FromObject(obj);

Variant

[Variant(typeof(MyVariantTag))] // Required to flag as variant and define options with enum
public class MyVariant
{
    [VariantTagProperty] // Flag for tag/enum property, not required if name is `Tag`
    public MyVariantTag Tag { get; set; }
    [VariantValueProperty] // Flag for value property, not required if name is `Value`
    public object? Value { get; set; }
}

public enum MyVariantTag
{
    [CandidName("o1")] // Used to override name for candid
    Option1,
    [CandidName("o2")]
    [VariantType(typeof(string))] // Used to specify if the option has a value associated
    Option2
}

Or if variant options have no type, just an Enum can be used

public enum MyVariant
{
    [CandidName("o1")]
    Option1,
    [CandidName("o2")]
    Option2
}

Record

public class MyRecord
{
    [CandidName("title")] // Used to override name for candid
    public string Title { get; set; }
    [CandidName("is_good_title")]
    public bool IsGoodTitle { get; set; }
}

NOTE: [CandidName(...)] is not needed if the property name is exactly the same as the candid name

// Equivalent to above
public class MyRecord
{
    public string title { get; set; }
    public bool is_good_title { get; set; }
}

Other

(C# type) -> (Candid type)

UnboundedUInt -> Nat
byte -> Nat8
ushort -> Nat16
uint -> Nat32
ulong -> Nat64
UnboundedInt -> Int
sbyte -> Int8
short -> Int16
int -> Int32
long -> Int64
string -> Text
float -> Float32
double -> Float64
bool -> Bool
Principal -> Principal
List<T> -> Vec T
T[] -> Vec T
CandidFunc -> Func
OptionalValue<T> -> Opt T
EmptyValue -> Empty
ReservedValue -> Reserved
NullValue -> Null

Parse Candid from Text

string text = "record { field_1:nat64; field_2: vec nat8 }";
CandidRecordType type = CandidTextParser.Parse<CandidRecordType>(text);

Generate Candid Text representation

var type = new CandidRecordType(new Dictionary<CandidTag, CandidType>
{
    {
        CandidTag.FromName("field_1"),
        CandidType.Nat64()
    },
    {
        CandidTag.FromName("field_2"),
        new CandidVectorType(CandidType.Nat8())
    }
});
string text = CandidTextGenerator.Generator(type, IndentType.Tab);

Client Generator

Usage (dotnet tool)

Install with dotnet tools

dotnet tool install -g EdjCase.ICP.ClientGenerator

Run tool

(First run only) Initialize config file and update generated file

candid-client-generator init ./

Creates candid-client.toml file to update in specified directory

Example:

namespace = "My.Namespace" # Base namespace used for generated files
output-directory = "./Clients" # Directory to put clients. Each client will get its own sub folder based on its name

[[clients]]
name = "Dex" # Used for the name of the folder and client class
type = "file" # Create client based on service definition file
file-path = "./ServiceDefinitionFiles/Dex.did" # Service definition file path

# Can specify multiple clients by defining another
[[clients]]
name = "Governance"
type = "canister" # Create client based on canister
canister-id = "rrkah-fqaaa-aaaaa-aaaaq-cai" # Canister to create client for

Generate clients

candid-client-generator ./

or

candid-client-generator gen ./

Internet Identity

Experimental library

• Only works for Windows right now

Usage

ulong anchor = 1; // Internet Identity anchor
string hostname = "nns.ic0.app"; // Hostname to login to
LoginResult result = await Authenticator
    .WithHttpAgent() // Use http agent to communicate to the Internet Identity canister
    .LoginAsync(anchor, hostname);

DelegationIdentity identity = result.GetIdentityOrThrow(); // Gets the generated identity or throws if login failed

var agent = new HttpAgent(identity); // Use in agent to make authenticated requests

Links

• IC Http Interface Spec
• Candid Spec
• Candid Decoder
• Candid UI Tester