Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/ic4j/ic4j-agent

IC4J Agent for the Internet Computer
https://github.com/ic4j/ic4j-agent

android dfinity icp java

Last synced: 7 days ago
JSON representation

IC4J Agent for the Internet Computer

Awesome Lists containing this project

README 

        
# dfinity-agent

Read complete documentation here 

https://docs.ic4j.com.



IC4J Java open source libraries provide a range of tools and interfaces for Java developers to interact with the Internet Computer network and build decentralized applications on top of it.





https://dfinity.org/




The code is implementation of the Internet Computer Interface protocol 





https://sdk.dfinity.org/docs/interface-spec/index.html




and it's using Dfinity Rust agent as an inspiration, using similar package structures and naming conventions.





https://github.com/dfinity/agent-rs




# License



IC4J Agent is available under Apache License 2.0.



# Documentation



## Supported type mapping between Java and Candid



| Candid      | Java    |

| :---------- | :---------- | 

| bool   | Boolean | 

| int| BigInteger   | 

| int8   | Byte | 

| int16   | Short | 

| int32   | Integer | 

| int64   | Long | 

| nat| BigInteger   | 

| nat8   | Byte | 

| nat16   | Short | 

| nat32   | Integer | 

| nat64   | Long |

| float32   | Float | 

| float64   | Double | 

| text   | String | 

| opt   | Optional | 

| principal   | Principal | 

| vec   | array, List | 

| record   | Map, Class | 

| variant   | Map, Enum | 

| func   | Func | 

| service   | Service | 

| null   |Null | 



## Supported Identities



Anonymous

Implicit by default



### Basic Identity (Ed25519)



Either generate Key Pair



```

KeyPair keyPair = KeyPairGenerator.getInstance("Ed25519").generateKeyPair();



Identity identity = BasicIdentity.fromKeyPair(keyPair);

```



Or use PEM file



```

Identity identity = BasicIdentity.fromPEMFile(path);

```



### Secp256k1 Identity



Get Key Pair from PEM file



```

Identity identity = Secp256k1Identity.fromPEMFile(path);

```



For Basic and Identities we are using Bouncy Castle open source libraries. To add it to your Java code you can use this code



```

Security.addProvider(new BouncyCastleProvider());

```



## Supported Transports



### HTTP Transport



```

ReplicaTransport transport = ReplicaApacheHttpTransport.create("http://localhost:8000");

```

or for Android



```

ReplicaTransport transport = ReplicaOkHttpTransport.create("http://localhost:8000");

```



## Agent Class



Create Agent object



```

Agent agent = new AgentBuilder().transport(transport).identity(identity).build();

```



## IDLArgs



To pass arguments to the Internet Computer Canister methods



```

List args = new ArrayList();



BigInteger intValue =new BigInteger("10000");

			

args.add(IDLValue.create(intValue));			

			

IDLArgs idlArgs = IDLArgs.create(args);



byte[] buf = idlArgs.toBytes();

```



## Supported Raw Methods



### Query



To call query method



```

CompletableFuture response = agent.queryRaw(Principal.fromString(canister_id),

					Principal.fromString(canister_id), "echoInt", buf, ingressExpiryDatetime);



byte[] output = response.get();

IDLArgs outArgs = IDLArgs.fromBytes(output);

```



### Update



To call update method



```

CompletableFuture response = agent.updateRaw(Principal.fromString(canister_id),

					Principal.fromString(canister_id), "greet", buf, ingressExpiryDatetime);

```



### GetState



To call getState method to retrieve result of update method



```

RequestId requestId = response.get();



CompletableFuture statusResponse = agent.requestStatusRaw(requestId,

		Principal.fromString(canister_id));

```



## Supported Builders



### QueryBuilder



```

CompletableFuture response = QueryBuilder.create(agent, Principal.fromString(canister_id), "echoInt").expireAfter(Duration.ofMinutes(3)).arg(buf).call();



byte[] output = response.get();

IDLArgs outArgs = IDLArgs.fromBytes(output);

```



### UpdateBuilder



```

UpdateBuilder updateBuilder = UpdateBuilder

	.create(agent, Principal.fromString(canister_id), "greet").arg(buf);

	

					CompletableFuture builderResponse = updateBuilder.callAndWait(com.scaleton.dfinity.agent.Waiter.create(60, 5));

					

byte[] output = builderResponse.get();

IDLArgs outArgs = IDLArgs.fromBytes(output);	

```



## Dynamic Proxy with annotated facade interface



Additionally you can also use Dynamic Proxy Class with facade Java interface that maps methods in the Internet Computer Canister. Agent values can be replaced with Agent Java object  



```

@Agent(identity = @Identity(type = IdentityType.BASIC, pem_file = "./src/test/resources/Ed25519_identity.pem"), transport = @Transport(url = "http://localhost:8001"))

@Canister("rrkah-fqaaa-aaaaa-aaaaq-cai")

@EffectiveCanister("rrkah-fqaaa-aaaaa-aaaaq-cai")

public interface HelloProxy {

	

	@QUERY

	public String peek(@Argument(Type.TEXT)String name, @Argument(Type.INT) BigInteger value);

	

	@QUERY

	@Name("echoInt")

	public BigInteger getInt(BigInteger value);	

	

	@QUERY

	public CompletableFuture getFloat(Double value);

	

	@UPDATE

	@Name("greet")

	@Waiter(timeout = 30)

	public CompletableFuture greet(@Argument(Type.TEXT)String name);



}

```



Then create Dynamic Proxy object and call the method



```

HelloProxy hello = ProxyBuilder.create().getProxy(HelloProxy.class);

			

String result = hello.peek(value, intValue);

```



Use Dynamic Proxy with POJO Java Object mapped to Candid RECORD type



POJO Java class with Candid annotations



```

import java.math.BigInteger;



import org.ic4j.candid.annotations.Field;

import org.ic4j.candid.annotations.Name;

import org.ic4j.candid.types.Type;



public class Pojo {

	@Field(Type.BOOL)

	@Name("bar")

	public Boolean bar;



	@Field(Type.INT)

	@Name("foo")

	public BigInteger foo;

}

```



```

Pojo pojoValue = new Pojo();

				

pojoValue.bar = new Boolean(false);

pojoValue.foo = BigInteger.valueOf(43); 

				

Pojo pojoResult = hello.getPojo(pojoValue);

```



## JSON (Jackson) serialization and deserialization



Use JacksonSerializer to serialize Jackson JsonNode or Jackson compatible Pojo class to Candid



```

JsonNode jsonValue;

IDLType idlType;



IDLValue idlValue = IDLValue.create(jsonValue, JacksonSerializer.create(idlType));

List args = new ArrayList();

args.add(idlValue);



IDLArgs idlArgs = IDLArgs.create(args);



byte[] buf = idlArgs.toBytes();

```



Use JacksonDeserializer to deserialize Candid to Jackson JsonNode or Jackson compatible Pojo class



```

JsonNode jsonResult = IDLArgs.fromBytes(buf).getArgs().get(0)

	.getValue(JacksonDeserializer.create(idlValue.getIDLType()), JsonNode.class);

```



## XML (DOM) serialization and deserialization



Use DOMSerializer to serialize DOM Node to Candid



```

Node domValue;



IDLValue idlValue = IDLValue.create(domValue,DOMSerializer.create());

List args = new ArrayList();

args.add(idlValue);



IDLArgs idlArgs = IDLArgs.create(args);



byte[] buf = idlArgs.toBytes();

```



Use DOMDeserializer to deserialize Candid to DOM Node



```

DOMDeserializer domDeserializer = DOMDeserializer.create(idlValue.getIDLType()).rootElement("http://scaleton.com/dfinity/candid","data");

			

Node domResult = IDLArgs.fromBytes(buf).getArgs().get(0).getValue(domDeserializer, Node.class);

```



## JDBC (ResultSet) serialization



Use JDBCSerializer to serialize JDBC ResultSet to Candid



```

ResultSet result = statement.executeQuery(sql);

			

IDLValue idlValue = IDLValue.create(result, JDBCSerializer.create());

List args = new ArrayList();

args.add(idlValue);



IDLArgs idlArgs = IDLArgs.create(args);



byte[] buf = idlArgs.toBytes();

```



# Downloads / Accessing Binaries



To add IC4J Agent library to your Java project use Maven or Gradle import from Maven Central.





https://search.maven.org/artifact/org.ic4j/ic4j-agent/0.7.4/jar




```



  org.ic4j

  ic4j-agent

  0.7.4



  org.ic4j

  ic4j-candid

  0.7.4



```



```

implementation 'org.ic4j:ic4j-agent:0.7.4'

implementation 'org.ic4j:ic4j-candid:0.7.4'

```



## Dependencies



This this is using these open source libraries



### Apache HTTP Client V5

To provide HTTP POST and GET operations.



### Ok HTTP Client 

To provide HTTP POST and GET operations for Android.



### Jackson CBOR Serializer and Deserializer

To manage CBOR payloads.



### Bouncy Castle Cryptography Libraries

To manage Ed25519 and Secp256k1 signatures.



### Bouncy Castle Cryptography Libraries

To manage Ed25519 and Secp256k1 signatures.



### MIRACL Core Cryptographic Library

To manage BLS12381 algorithm. 



# Build



You need JDK 8+ to build Dfinity Agent.