Polygon ID SDK Plugin: Example App
To use Polygon ID Mobile SDK, we have created a Polygon ID SDK Plugin. This plugin helps you communicate with our Polygon ID Platform.
The following steps illustrate how to do initial setup to get things started and then use this plugin to create an identity, authenticate this identity, fetch a credential from an Issuer using identity, and generate a proof to verify (by Verifier) this credential.
Initial Setup
-
Install Flutter: Install Flutter SDK. To know the steps in detail, read the tutorial here.
-
Clone Repository: Clone the polygonid-sdk-repository.
-
Set Directory: On your Terminal, change the directory to
example
, which is a folder in thepolygonid-sdk-repository
.cd example
-
Set Dependencies: To use the Polygon ID Flutter SDK plugin, add the following dependencies to your
pubspec.yaml
file:environment:
sdk: ">=2.17.0 <3.0.0"
dependencies:
flutter: sdk: flutter polygonid_flutter-sdk: ^x.y.z
where "^x.y.z" stands for the version constraints (range of versions that are backward compatwith the x.y version.
Read more here.
-
Get Dart packages: While in the
example
directory, run the following command:The system runs the command and shows:flutter pub get flutter pub run build_runner build --delete-conflicting-outputs
Running "flutter pub get" in example...
where
pub
command (in Dart) invokes a set of tools for managing Dart packages andpub get
downloads these packages for your Dart project. Theflutter pub get
indicates that the command is run via flutter SDK. -
Build your first project and run it. For more details, click here.
While running a Flutter command, if you encounter a command not found: flutter error, make sure that the path set above is correct. If you still encounter the error, install Vim emulation for Visual Studio Code as an extension and follow these steps:
- Run the following command:
vim $HOME/.zshrc
where we assume that you are working in the Z shell.
If you are using the Bash shell, you can run this command:
vim $HOME/.bashrc
To know your shell, type:
echo $SHELL
/bin/zsh
- This opens the
.zshrc
configuration window (for the Z Shell). Press "I" to initiate the insert mode. - Run the following command to set your path variable:
export PATH="$PATH:/Flutter-Directory-Path/flutter/bin"
- Press
Escape
on your keyboard and then enter the following command:
:wq!
Enter
. This saves the file in Vim and exits the editor (wq
stands for write and quit).
- Run your flutter commands.
General Flow
Overview
In the upcoming sections, we shall see the general flow of how to use the Polygon ID SDK plugin. The steps are summarised as:
A. Identity
- Initialise Polygon ID SDK.
- Create an Identity for the wallet.
- Get (Retrieve) Identifier from the Identity created in the previous step.
- Remove Identity (only if required).
- Get iden3Message from Issuer.
- Authenticate Identity using Identifier, iden3Message, and Private Key.
B. Credential
- Create CredentialRequestEntity from the Iden3Message received from an Issuer.
- Fetch and Save credentials (received from Issuer) on SDK using CredentialRequestEntity, Identifier, and Private Key.
- Get credentials that are saved on wallet SDK. One can also retrieve them with credential IDs.
- Remove credential (only if required).
- Update credential (only if required).
C. Proof
- Generate zero-knowledge proof using iden3Message, Identifier, and Private Key.
** SDK**
Initiate Polygon ID SDK
To start using Polygon ID SDK, an integrator needs to initialize it first. This is done inside the dependency injection initializer using await PolygonIdSDK.init()
.
import 'package:flutter/material.dart';
import 'package:polygonid_flutter_sdk/sdk/polygon_id_sdk.dart';
Future<void> main() async {
await PolygonIdSdk.init();
runApp(const App());
}
If the SDK has not been initialized, the system throws an exception: PolygonIsSdkNotInitializedException
indicating that the Polygon ID SDK has not been initialized and must be initialized first with await PolygonIdSDK.init()
.
After the SDK initialization, the Integrator will need to use the instance of PolygonIdSDK:
PolygonIdSdk.I
Get current environment
The current environment can be retrieved using getEnv()
, it gives an EnvEntity
:
PolygonIdSdk.I.getEnv();
Get Iden3Message from a String
An Integrator uses iden3Message
to communicate with an Issuer/Verifier. This 'iden3message' is created from the QR code scanned by the user on his/her wallet. The getIden3Message()
uses a string message (created after scanning the QR code) as the input parameter and generates iden3Message
.
PolygonIdSdk.I.iden3comm.getIden3Message(message: message);
Steps in Detail
A. Identity
This part of the flow consists of initialising Polygon ID SDK, creating an identifier for an identity and retrieving it, and using the identifier to authenticate the Identity.
1. Create Identity
After SDK initialization, the SDK checks the existence of an Identifier that was previously created with the addIdentity()
function.
If no previously created Identifier is found, the SDK first needs to create an identity first using identity.addIdentity()
function.
Future<void> addIdentity() async {
// we get the sdk instance previously initialized
final sdk = PolygonIdSdk.I;
PrivateIdentityEntity identity = await sdk.identity.addIdentity(secret: secretKey);
}
You can retrieve your private key
from the PrivateIdentityEntity
specified in the code above. Keep this private key safe; it will be used in a few other SDK methods as you will see in the following steps.
Note: It is not mandatory to pass the
secret
as the input parameter in the function. If you do not pass it, a randomsecret
is generated by the system.
3. Get did Identifier
This retrieves the did identifier
by passing the environment detail and private key
input parameter to the getDidIdentifier()
function; please note that the private key
is generated from PrivateIdentityEntity
that we generated via addIdentity()
function in the previous section.
PolygonIdSdk.I.identity.getDidIdentifier(
privateKey: privateKey,
blockchain: env.blockchain,
network: env.network,
profileNonce: profileNonce);
4. Remove Identity
To remove an existing Identity (use this only when required), you need to call the identity.removeIdentity()
with did identifier
and the privateKey
as the input parameters.
Future<void> removeIdentity({
required String privateKey,
required String did,
}) async {
await sdk.identity.removeIdentity(
privateKey: privateKey,
genesisDid: did,
);
5. Authenticate Identity
We use authenticate()
to authenticate an identity by using privateKey
, did identifier
, and iden3Message
as the input parameters.
Future<void> authenticate({
required Iden3MessageEntity iden3message,
required String genesisDid,
required String privateKey,
}) async {
await sdk.iden3comm.authenticate(
iden3message: iden3message,
genesisDid: genesisDid,
privateKey: privateKey,
);
}
B. Credential
This part of the flow consists of retrieving credentials from an Issuer and saving them in the wallet. One or more credentials can be retrieved and one or more credentials can be removed from the wallet.
1. Fetch and Save Credentials
This functionality consists of retrieving credentials from an Issuer (by fetching them) and then saving them on the wallet.
This involves:
- Getting
Iden3Message
(see above). - Fetching and saving credentials.
List<ClaimEntity> claimList =
await sdk.iden3comm.fetchAndSaveClaims(
message: iden3message as OfferIden3MessageEntity,
genesisDid: didIdentifier,
privateKey: privateKey,
);
2. Get Credentials
Once credentials have been saved on the wallet SDK, these can be retrieved by the Integrator using credential.getClaims()
with did identifier
, and privateKey
used as the mandatory input parameters and filters
as an optional one. Filters
let an Integrate get credentials based on some pre-determined criteria.
List<ClaimEntity> claimList = await sdk.credential.getClaims(
filters: filters,
genesisDid: did,
privateKey: privateKey,
);
3. Get Credentials by Ids
This functionality lets an Integrator get credentials from an Issuer based on their IDs. The claimId
, did identifier
, and privateKey
are passed as input parameters to the credential. getClaimsByIds()
function and a list of credentials in the form of ClaimEntity
are retrieved. The ID of each credential is stored on the SDK from where they can be retrieved.
Future<void> getClaimsByIds({
required List<String> claimIds,
required String genesisDid,
required String privateKey,
}) async {
List<ClaimEntity> claimList = await sdk.credential.getClaimsByIds(
claimIds: claimIds,
genesisDid: genesisDid,
privateKey: privateKey,
);
}
4. Remove a Credential
A credential can be removed from the wallet using credential.removeClaim()
by passing claimId
(the ID of the credential to be removed), the did identifier
and the privateKey
as the input parameters.
Future<void> removeClaim({
required String claimId,
required String genesisDid,
required String privateKey,
}) async {
await sdk.credential.removeClaim(
claimId: claimId,
genesisDid: genesisDid,
privateKey: privateKey,
);
}
5. Remove Multiple Credentials
This is similar to removing a single credential described above. In this case, you need to pass a list of claimids
to be removed, the did identifier
, and the privateKey
as the input parameters to credential.removeClaims()
.
Future<void> removeClaims({
required List<String> claimIds,
required String genesisDid,
required String privateKey,
}) async {
await sdk.credential.removeClaims(
claimIds: claimIds,
genesisDid: genesisDid,
privateKey: privateKey,
);
}
6. Update Credential
To update a credential, the credential.updateClaim()
function is used with the following fields passed as input parameters:
claimId
did identifier
privateKey
- other information such as identity
state
,issuer
, credential'sexpiration
date,type
of credential, etc.
Future<void> updateClaim({
required String claimId,
required String genesisDid,
required String privateKey,
String? issuer,
ClaimState? state,
String? expiration,
String? type,
Map<String, dynamic>? data,
}) async {
PolygonIdSdk sdk = PolygonIdSdk.I;
await sdk.credential.updateClaim(
id: claimId,
genesisDid: genesisDid,
privateKey: privateKey,
issuer: issuer,
state: state,
expiration: expiration,
type: type,
data: data,
);
}