Agent Setup
This guide assumes you have followed the Prerequisites, and you have a valid Node.JS or React Native project setup.
Aries Framework JavaScript is still in active development, and as such some APIs are still experimental. When using any experimental features, make sure to use an exact version of AFJ (0.4.0
) instead of a range (^0.4.0
), to prevent accidental breaking changes. If you're not leveraging any experimental features, you can use a range (^0.4.0
) to get the latest bugfixes and features.
For AFJ 0.4.x
, the following features are experimental:
- Implementing your own
AnonCredsRegistry
and AnonCreds service implementation. - Using the shared component libraries from
@aries-framework/aries-askar
,@aries-framework/indy-vdr
and@aries-framework/anoncreds-rs
- Using OpenID4VC from the
@aries-framework/openid4vc-client
module - W3C JWT Verifiable Credentials
- Using multi-tenancy from the
@aries-framework/tenants
module - Using BBS+ Signatures from the
@aries-framework/bbs-signatures
module - Using the cheqd module from the
@aries-framework/cheqd
module
Installing the required dependencies
First we have to install the minimal amount of dependencies that are required for configuring an Aries Framework JavaScript (AFJ) agent.
- Node.JS
- React Native
yarn add @aries-framework/core@^0.4.0 @aries-framework/node@^0.4.0
yarn add @aries-framework/core@^0.4.0 @aries-framework/react-native@^0.4.0 react-native-fs react-native-get-random-values
Additional setup
- Node.js
- React Native
No additional setup is required for Node.JS
Since React Native does not have an implementation
for
crypto.getRandomValues()
we have to setup a polyfill for this. We have to do this at the entrypoint of
the application. This could is most likely index.(js|ts|jsx|tsx)
at the root
of your application.
+ import 'react-native-get-random-values'
In addition you need add support for resolving modules with the .cjs
extension, as this is used by some of AFJ's dependencies and not automatically supported by React Native.
module.exports = {
// ... other Metro config options ...
resolver: {
// make sure this includes `cjs` (and other extensions you need)
sourceExts: ['js', 'json', 'ts', 'tsx', 'cjs'],
},
}
Finally, if you're using Expo you need to add a custom resolution 'hack' that removes support for the legacy unimodules.
Yarn
For yarn we can replace the @unimodules/react-native-adapter
and @unimodules/core
dependencies with an empty directory. Make sure to create the noop
directory in the root of your project and create a .gitkeep
file in the directory so that the directory is committed to your repository.
{
// ... other package.json options ...
"resolutions": {
"@unimodules/react-native-adapter": "./noop",
"@unimodules/core": "./noop"
}
}
NPM
Not supported at the moment. NPM overrides work different than Yarn resolutions, and thus we can't use the same trick. If you're using NPM, feel free to open a PR with a working solution.
Setting up the agent
this section does not assume any knowledge of the agent configuration. In the Agent Config tutorial we will discuss in-depth what every field in the configuration does and when to set it.
In order to use the agent in the application we have to configure and initialize it. This following configuration is quite generic and possibly not enough for your specific use cases. Please refer to the tutorials for a more use-case-specific agent setup.
- Node.JS
- React Native
import type { InitConfig } from '@aries-framework/core'
import { Agent } from '@aries-framework/core'
import { agentDependencies } from '@aries-framework/node'
const config: InitConfig = {
label: 'docs-agent-nodejs',
walletConfig: {
id: 'wallet-id',
key: 'testkey0000000000000000000000000',
},
}
const agent = new Agent({
config,
dependencies: agentDependencies,
})
import type { InitConfig } from '@aries-framework/core'
import { Agent } from '@aries-framework/core'
import { agentDependencies } from '@aries-framework/react-native'
const config: InitConfig = {
label: 'docs-agent-react-native',
walletConfig: {
id: 'wallet-id',
key: 'testkey0000000000000000000000000',
},
}
const agent = new Agent({
config,
dependencies: agentDependencies,
})
Adding a wallet and storage implementation
After creating the Agent
instance, we need to provide the agent with a wallet and storage implementation. AFJ provides a few implementations out of the box, but you can also implement your own. Currently the following Wallet and Storage implementations are supported out of the box. Follow the specific guides to set up the wallet and storage implementation of your choice.
- Aries Askar - Recommended.
- Indy SDK - Legacy. Will be deprecated in the future.
📄️ Aries Askar
Aries Askar provides secure, encrypted storage and cryptographic support for encrypting, decrypting, signing and verifying data. It also provides both the Wallet and StorageService implementations for the agent.
📄️ Indy SDK
Indy SDK provides a distributed ledger based foundation for self-sovereign identity. It can provide the Wallet and StorageService implementations for the agent, as well as a way to interact with Indy ledgers and an implementation of the legacy (v0.1) AnonCreds Specification
Setting up the transports
Finally, we have to set an outbound transport that will handle traffic from the agent. It is also possible to set an inbound transport in the same way as the outbound transport.
- Node.js
- React Native
Sets up an WS outbound and HTTP inbound and outbound transport.
import { HttpOutboundTransport, WsOutboundTransport } from '@aries-framework/core'
import { HttpInboundTransport } from '@aries-framework/node'
// ... agent setup from prevous section ...
agent.registerOutboundTransport(new HttpOutboundTransport())
agent.registerOutboundTransport(new WsOutboundTransport())
agent.registerInboundTransport(new HttpInboundTransport({ port: 3000 }))
For mobile agents the WebSocket transport is often required. We will go into more depth about the reasons for this in the mediation section.
import { HttpOutboundTransport, WsOutboundTransport } from '@aries-framework/core'
// ... agent setup from prevous section ...
agent.registerOutboundTransport(new HttpOutboundTransport())
agent.registerOutboundTransport(new WsOutboundTransport())
Initializing the agent
Finally, we can initialize the agent and it's ready for use.
- Node.js
- React Native
agent
.initialize()
.then(() => {
console.log('Agent initialized!')
})
.catch((e) => {
console.error(`Something went wrong while setting up the agent! Message: ${e}`)
})
agent
.initialize()
.then(() => {
console.log('Agent initialized!')
})
.catch((e) => {
console.error(`Something went wrong while setting up the agent! Message: ${e}`)
})
Next Steps
Now that you have your agent setup, it's time to start building your application. Head over to the tutorials page to get started.
📄️ Tutorials
In this section we will explain some features that everyone will use. This
📄️ Create a Connection
In this tutorial we will create a connection as Acme Corp with Bob. We will