This specification describes a communication protocol between dapps (decentralized applications) and wallets. It defines messages that both sides should use to interact with each other and provides guidelines on how to process them.
The purpose of the permission messages is to establish a connection between a relying party and a wallet, grant the
relying party access to public parts of the user's identity and define the scope of actions the relying part is allowed
to perform.
sequenceDiagram
participant D as Dapp
participant W as Wallet
participant U as User
D ->> W: Permission
Note right of D: Version, dapp metadata, requested networks + scopes and challenge
alt Version isn't supported
W ->> D: Error: VERSION_NOT_SUPPORTED
else Network isn't supported
W ->> D: Error: NETWORK_NOT_SUPPORTED
else
W ->> U: Dapp would like to connect
Note right of W: Show origin to user e.g. https://example.com
alt User approves
U ->> W: Approve
Note right of W: Store origin and the permission scopes granted
W ->> D: Version wallet metadata, granted networks + scopes and identities with signatures
Note right of D: Verify all identity signatures for concatenation: "\x0Aic-wallet-challenge" + challenge given in request
else User rejects
U ->> W: Reject
W ->> D: Error: NOT_GRANTED
end
end
Once the connection between the relying party and the wallet is established, and the relying party has been granted
the canister_call permission scope, the relying party can request the wallet to execute canister calls.
sequenceDiagram
participant D as Dapp
participant W as Wallet
participant U as User
participant C as Canister
D ->> W: Canister call
Note right of D: Version, network canister id, sender, method and arg
alt Version isn't supported
W ->> D: Error: VERSION_NOT_SUPPORTED
else Network isn't supported
W ->> D: Error: NETWORK_NOT_SUPPORTED
else Origin isn't stored or doesn't have canister_call permission
W ->> D: Error: NOT_GRANTED
else
alt Canister supports ICRC-21
W ->> C: Get consent message for the canister call method and arguments
C ->> W: Textual consent message
W ->> U: Show consent message to user
else Canister supports ICRC-1
W ->> U: Show transaction details like recipient and amount
else Canister does not support any of the above
W ->> U: Show user canister id, method and arguments
Note right of W: Decodes the arguments and shows "as is" in e.g. a visual tree<br>also a warning could be shown regarding missing consent message
end
alt User approves
U ->> W: Approve canister call
W ->> C: Make canister call
C ->> W: Response certificate
W ->> D: Content map (all data sent in request to canister above) and certificate
Note right of D: Verify content map matches request canister id, method and arguments
Note right of D: Verify certificate signature is valid
Note right of D: Calculate request id from content map and verify certificate contains its reply
else User cancels
U ->> W: Cancel canister call
W ->> D: Error: ABORTED
end
end