Skip to content

Wallet Service

The wallet service is the main interface for interacting with a cloud wallet.

Wallets vs Accounts

Wallets and accounts are related and often interchangeable -- each account has an associated wallet, and operations on a wallet are performed using an account's access token.

Every account has exactly one wallet.

Wallet Standard

This service is designed to follow the recommendations of the Universal Wallet 2020 specification by the W3C Community Credentials Group.

Create Wallet

A wallet is created whenever an account is created.

Therefore, to create a wallet, you'll need to create a new account.

Insert Item

Stores a credential (or any other JSON object) in a wallet.

trinsic wallet insert-item --item <INPUT_JSON_FILE>

let insertItemResponse = await trinsic.wallet().insertItem(
  InsertItemRequest.fromPartial({
    itemJson: issueResponse.signedDocumentJson,
  })
);

var insertItemResponse = await trinsic.Wallet.InsertItemAsync(new() { ItemJson = credentialJson.DocumentJson });

insert_response = await trinsic.wallet.insert_item(
    request=InsertItemRequest(
        item_json=credential, item_type="VerifiableCredential"
    )
)

insertResponse, err := trinsic.Wallet().InsertItem(context.Background(), &wallet.InsertItemRequest{
    ItemJson: credentialJson,
    ItemType: "VerifiableCredential",
})

var insertResponse =
    trinsic
        .wallet()
        .insertItem(
            InsertItemRequest.newBuilder()
                .setItemJson(credentialJson)
                .setItemType("VerifiableCredential")
                .build())
        .get();

InsertItemRequest
Request to insert a JSON document into a wallet
item_json
string
Document to insert; must be stringified JSON
item_type
optional string
Item type (ex. "VerifiableCredential")

InsertItemResponse
Response to InsertItemRequest
item_id
string
ID of item inserted into wallet

What can be stored in a wallet?

Wallets are mainly intended to hold Verifiable Credentials, but can technically store any JSON blob.

If you store a Verifiable Credential in a Wallet, ensure that its item_type is VerifiableCredential.

Otherwise, ensure its item_type is not VerifiableCredential.

Search Wallet

Searches a wallet, returning all matching items, and a continuation_token to paginate large result sets.

If no query is specified, this call by default returns the first 100 items in the wallet.

trinsic wallet search

let items = await trinsic.wallet().search();

var walletItems = await trinsic.Wallet.SearchWalletAsync(new());

wallet_items = await trinsic.wallet.search_wallet()

searchResponse, err := trinsic.Wallet().SearchWallet(context.Background(), &wallet.SearchRequest{})

var walletItems = trinsic.wallet().searchWallet().get();

SearchRequest
Request to search items in wallet
query
string
SQL Query to execute against items in wallet
continuation_token
optional string
Token provided by previous SearchResponse if more data is available for query

SearchResponse
Response to SearchRequest
items
string[]
Array of query results, as JSON strings
has_more
bool
Whether more results are available for this query via continuation_token
continuation_token
string
Token to fetch next set of results via SearchRequest

Verifiable Presentation Request Spec

In the future, this endpoint will support the Verifiable Presentation Request Spec .

The Search endpoint supports SQL queries through the query parameter.

This allows for arbitrary query predicates, as well as more advanced functionality -- such as modifying the output format.

Schema

Any table name may be used in your query (we use c here) -- it doesn't matter what it is.

Name Type Description
id string Corresponds to the item_id returned when item was inserted into wallet
type string Specified via item_type when item was inserted into wallet
data object The JSON object passed via item_json when item was inserted into wallet

Note that data is an object, not a string; thus, any of its sub-fields may be queried against.

For example, SELECT * FROM c WHERE c.data.someField = 'Hello, World!' would match against the following JSON object inserted via InsertItem:

{ 
    "someField": "Hello, World!"
}

Common SQL Queries

Paging

Paging uses the OFFSET clause that takes in a value indicating how many records should be skipped in the returned query. To specify the size of the result set (page size) use the LIMIT clause.

SELECT * FROM c OFFSET 10 LIMIT 5

Sorting

The optional ORDER BY clause specifies the sorting order for results returned by the query. To control sorting order, specify ASC or DESC at the end; if not specified ascending order is used by default.

SELECT * FROM c ORDER BY c.credential.issued DESC

Filtering

The optional WHERE clause (WHERE <filter_condition>) specifies condition(s) that the source JSON items must satisfy for the query to include them in results. A JSON item must evaluate the specified conditions to true to be considered for the result. The index layer uses the WHERE clause to determine the smallest subset of source items that can be part of the result.

SELECT * FROM c WHERE c.name = 'Trinsic' AND c.dateCreated >= "2020-09-30T23:14:25.7251173Z"

Grouping

The GROUP BY clause divides the query's results according to the values of one or more specified properties. Examples and detailed description on working with grouped results can be found here

Additional Resources

You can read the full documentation on working with SQL queries on the Azure Cosmos DB website .