XRP Ledger Namespace - SIWx

Author Anton Dalgren
Discussions-To https://github.com/ChainAgnostic/namespaces/pull/57/
Status Draft
Type Standard
Created 2023-08-12
Requires CAIP-122, CAIP-2, CAIP-10


For context, see the CAIP-122 specification.


This specification provides the signing algorithm to use, the type of the signing algorithm to identify it, and a method for signature creation and verification as required by CAIP-122.


Signing Algorithm

XRPL uses the ECDSA secp256k1 or EdDSA Ed25519 signing algorithm for signing and verifying messages depending on the type of the keypair that is being used. A secp256k1 keypair will be using the secp256k1 algorithm and a Ed25519 keypair will be using the Ed25519 algorithm.

Prior to the message being signed using secp256k1, it needs to be hashed using the 512bit digest of the SHA-2 algorithm, commonly referred to as SHA-512 and specified in RFC4634. Correspondingly, a message needs to be serialized to bytes prior to signing it with the Ed25519 algorithm.

Signature Type

We propose using the signature type xrpl:secp256k1 and xrpl:ed25519 to refer to the chain and algorithm used uniquely.

Signature Meta

We propose that the signature meta contains the public key of the signer. This is to allow for the requester to verify that the signature belongs to the specified public key. The requester is also responsible for verifying that the public key that was used to sign the message is properly associated with the address in the payload.

type SignatureMeta struct {
  SigningPubKey String

Signature Creation

The abstract data model must be canonicalized to a string representation in an unambigious format, and then the string serialized to the proper binary format mentioned above to be signed over with the proper algorithm. Depending on the method or libraries used for signatures, this conversion may or may not happen automatically. For example, if using ripple-keypairs, you will need to convert the key to a byte representation before signing using Ed25519 and for secp256k1 the library will handle hashing and signing internally.

We propose the following string format, inspired by the ABNF in EIP-4361.

${domain} wants you to sign in with your XRPL account:


URI: ${uri}
Version: ${version}
Chain ID: ${chain-id}
Nonce: ${nonce}
Issued At: ${issued-at}
Expiration Time: ${expiration-time}
Not Before: ${not-before}
Request ID: ${request-id}
- ${resources[0]}
- ${resources[1]}
- ${resources[n]}

For example,

service.org wants you to sign in with your XRPL account:

I accept the ServiceOrg Terms of Service: https://service.org/tos

URI: https://service.org/login
Version: 1
Chain ID: 0
Nonce: 32891757
Issued At: 2021-09-30T16:25:24.000Z
- ipfs://Qme7ss3ARVgxv6rXqVPiikMJ8u2NLgmgszg13pYrDKEoiu
- https://example.com/my-web2-claim.json

The preceeding example would be hashed to 4beb3f7d5c8bf8deab467de033628274a9053f688f82e0f023cddcb0564cfc9a prior to being signed using the secp256k1 algorithm.

The serialization of this string prior to signing with Ed25519 would produce:


Signature Verification

Signature verification behaves similarly. We can use standard secp256k1 orEd25519 signature verification. We convert the input message to a bytes representation of the string format, then verify the signature over that using the public key. Both of these verification methods are available in the ripple-keypairs library.



Please cite this document as:

Anton Dalgren, "namespaces/xrpl-caip122: XRP Ledger Namespace - SIWx [DRAFT]," Chain Agnostic Namespaces, xrpl-caip122, August 2023 / . [Online serial]. Available: https://github.com/ChainAgnostic/namespaces/xrpl-caip122.md