EdjCase.ICP.Candid 2.1.0

ICP.NET

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

• Agent

  • Library to communicate to and from the Internet Computer
  • PreGenerated ICRC1 Client
  • 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);

Using the ICRC1 PreGenerated Client

Instantiate an ICRC1Client by passing the HttpAgent instance and the canister ID of the ICRC1 canister as parameters:

IAgent agent = new HttpAgent(identity);
Principal canisterId = Principal.FromText("<canister_id>");
ICRC1Client client = new ICRC1Client(agent, canisterId);

Use the methods of the ICRC1Client to communicate with the ICRC1 canister:

// Get the name of the token
string name = await client.Name();

// Get the balance of a specific account
Account account = new Account
{
    Id = Principal.FromText("<account_id>")
};
UnboundedUInt balance = await client.BalanceOf(account);

// Transfer tokens from one account to another
TransferArgs transferArgs = new TransferArgs
{
    To = new Account
    {
        Id = Principal.FromText("<to_account_id>")
    },
    Amount = 1,
    Memo = "<memo>"
};
TransferResult transferResult = await client.Transfer(transferArgs);

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. If not specified, will use current directory
no-folders = false # If true, will put all the files in a single directory

[[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
output-directory = "./Clients/D" # Override base output directory, but this specifies the subfolder
no-folders = false # If true, will put all the files in a single directory


# 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 ./

Config file options

Top Level:

• namespace - (Text) REQUIRED. The base namespace used in all C# files generated. Files generated in a sub-folder will have a more specific namespace to match. This namespace can be overidden per client.
• output-directory - (Text) OPTIONAL. Directory to put all generated files. Each client will have a sub-folder within the output directory that will match the client name. If not specified, the working directory will be used
• no-folders - (Bool) OPTIONAL. If true, no sub-folders will be generated for the clients or the models within the clients. All generated files will be in a flat structure. Defaults to false
• url - (Text) OPTIONAL. Sets the boundry node url to use for making calls to canisters on the IC. Can be set to a local developer instance/localhost. Defaults to 'https://ic0.app/'. This setting is only useful for clients of generation type canister
• feature-nullable - (Bool) Optional. Sets whether to use the C# nullable feature when generating the client (like object?). Defaults to true
• keep-candid-case - (Bool) Optional. If true, the names of properties and methods will keep the raw candid name. Otherwise they will be converted to something prettier. Defaults to false

Client Level:

• name - (Text) REQUIRED. The name of the sub-folder put the client files and the prefix to the client class name.
• type - (Text) REQUIRED. An enum value to indicate what type of client generation method to use. Each enum value also has associated configuration settings. Options:
  • file - Will create a client based on a service definition file (*.did)
    • file-path - (Text) REQUIRED. The file path to the *.did file to generate from
  • canister - Creates a client based on a canister id
    • cansiter-id - (Text) REQUIRED. The principal id of the canister to generate a client for
• output-directory - (Text) OPTIONAL. Directory to put all generated client files. Overrides the top level output-directory. NOTE: this does not create a sub-folder based on the client name like the top level output-directory does
• no-folders - (Bool) OPTIONAL. If true, no sub-folders will be generated for the client. All generated files will be in a flat structure. Defaults to false. Overrides the top level no-folders
• feature-nullable - (Bool) Optional. Sets whether to use the C# nullable feature when generating the client (like object?). Defaults to true. Overrides the top level feature-nullable
• keep-candid-case - (Bool) Optional. If true, the names of properties and methods will keep the raw candid name. Otherwise they will be converted to something prettier. Defaults to false. Overrides the top level keep-candid-case

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