EdjCase.ICP.Agent 2.0.0-beta.2

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

• Samples

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

Agent

Usage (Manual)

// Create identity
var identity = new AnonymousIdentity();

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

// Create Candid arg to send in request
ulong proposalId = 1234;
CandidArg arg = CandidArg.FromCandid(
    CandidValueWithType.FromObject(proposalId)
);

// 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);

QueryReply reply = response.ThrowOrGetReply();
// Convert to custom class
ProposalInfo? info = reply.Arg.Values[0].ToObjectOrDefault<ProposalInfo>()

Usage (w/ Client Generator)

• Run Client Generator on *.did file (see Client Generator below)

// Create identity
var identity = new AnonymousIdentity();

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

// 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
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 custom classes

// Custom class
public class MyObj
{
    public string Title { get; set; }
    public bool IsGoodTitle { get; set; }
}

// Deserialize
CandidArg arg = CandidArg.FromBytes(rawCandidBytes);
MyObj obj = arg.Values[0].ToObject<MyObj>();

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

Parse from Text

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

Generate Text representation

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

Client Generator

Usage (Code)

    // Location of the `*.did` file to parse from
    string candidFilePath = "location/to/service.did";

    // Directory to create *.cs source code.
    string outputDirectory = "location/to/output";

    // Base namespace to give all *.cs files
    string @namespace = "My.Namespace.IC"

    // Optional, will use file name or type name if unspecified
    string? clientName = "MyClient";
    ClientFileGenerator.WriteClientFiles(candidFilePath, outputDirectory, @namespace, clientName);

Usage (dotnet tool)

Install with dotnet tools

dotnet tool install -g EdjCase.ICP.ClientGenerator

Run tool

candid-client-generator -f "location/to/service.did" -o "location/to/output" -n "My.Namespace.IC" -c "MyClient"

Links

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