Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/ic4j/ic4j-agent
IC4J Agent for the Internet Computer
https://github.com/ic4j/ic4j-agent
android dfinity icp java
Last synced: 5 days ago
JSON representation
IC4J Agent for the Internet Computer
- Host: GitHub
- URL: https://github.com/ic4j/ic4j-agent
- Owner: ic4j
- License: apache-2.0
- Created: 2022-01-15T01:14:42.000Z (almost 3 years ago)
- Default Branch: master
- Last Pushed: 2024-09-16T21:35:24.000Z (about 2 months ago)
- Last Synced: 2024-09-17T02:47:43.105Z (about 2 months ago)
- Topics: android, dfinity, icp, java
- Language: Java
- Homepage:
- Size: 298 KB
- Stars: 22
- Watchers: 1
- Forks: 7
- Open Issues: 4
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
- awesome-internet-computer - ic4j-agent - Libraries for interfacing with the IC using Java (Android compatible). (Client Libraries (Agents) / Java)
- awesome-icp - ic4j/ic4j-agentJ
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.
The code is implementation of the Internet Computer Interface protocol
https://sdk.dfinity.org/docs/interface-spec/index.htmland 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.4org.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.