Skip to content

Signing transactions ​

Every upload and every flag sent through the API is a transaction that the client signs with the user's signing key pair before submitting it.

Every operation that contains .../assemble in its path has a mirroring endpoint (e.g., assembling a contribution -> submitting a contribution). The first request returns the transaction as a transactionHex string. The client signs it and sends the signed Hex string in the second request.

For reference, see any of the following tutorials:

The sequence of events to sign a transaction is the following:

  1. Take the user's signing key pair from the Profile page of the web app, under Signing key.
  2. Retrieve the Hex string of the required transaction from the .../assemble request.
  3. Hash the payload of the transaction and sign the hash.
  4. Put the public key and the signature in front of the payload.

The resulting Hex string is sent as the body of the request, as plain text and without quotes, to the following endpoints:

http
POST /data/api/v1/contribution-management/contribution
PATCH /data/api/v1/contribution-management/contribution/flag

KEYS TO USE

Sign with the signing key pair, not with the authorization one. The Signing key on the Profile page has three rows:

RowLengthUse
Public key64 hex charactersGoes into the signed transaction.
Private key, standard Ed2551964 hex charactersThe key that Ed25519 libraries take.
Private key, 64-byte form128 hex charactersThe same private key followed by the public key. Its first 64 characters are the standard private key.

Format of the transaction ​

The transaction is a binary structure in the SCALE encoding, written as a Hex string.

An assembled transaction starts with the two bytes 01 00: the version and the number of signatures, which is zero. All bytes after them are the payload.

The signature is a standard Ed25519 signature over the hashed payload:

payload     = transaction without its first 2 bytes
digest      = BLAKE2b-256( payload )
digest[31] |= 1
signature   = Ed25519-Sign( signingPrivateKey, digest )

The signed transaction is the following sequence of bytes, written as a Hex string:

BytesLengthContent
011The version
041The number of signatures: one
001The signature algorithm: Ed25519
801The length of the public key
public key32The public key of the signing key pair
01 012The length of the signature
signature64The signature
payloadthe restThe payload, unchanged

Any cryptographic library that provides Ed25519 and BLAKE2b-256 can produce it, in any programming language. No SDK is required.

THE LAST BYTE OF THE DIGEST

Setting the low bit of the digest's last byte is required, as it is for the signature of an email address. It changes the digest for roughly half of all transactions. Check your implementation against the test vector: its digest is changed by this rule.

Examples ​

The examples below sign the transaction of the test vector with the test key pair.

python
# pip install cryptography
import hashlib

from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PrivateKey


def sign_transaction(public_key_hex: str, private_key_hex: str, transaction_hex: str) -> str:
    if not transaction_hex.startswith("0100"):
        raise ValueError("not an assembled transaction")
    payload = bytes.fromhex(transaction_hex[4:])

    # A 128-character key is the private key followed by the public key.
    key = Ed25519PrivateKey.from_private_bytes(bytes.fromhex(private_key_hex[:64]))
    digest = bytearray(hashlib.blake2b(payload, digest_size=32).digest())
    digest[31] |= 1
    signature = key.sign(bytes(digest)).hex()

    return "0104" + "0080" + public_key_hex + "0101" + signature + payload.hex()


print(sign_transaction(
    "bdebaf574c9dc2043a423acef76a4621924a405e713735ec8f21653abe3576a2",
    "c3396eb8c9acd64659cc2a258415b8aebd45abea4a5f02cb1163ee20956d9a11",
    "01005657f2d4a10100003c6578616d706c655f74656c65636f6d1461646d696e0004080d08013c6578616d706c655f74656c65636f6d1461646d696e0d0234636f6e747269627574696f6e730d0149035b7b226964223a223230332e302e3131332e392d3230332e302e3131332e39222c226674223a332c226f7267223a225345222c22647374223a224742222c22737473223a302c226564223a313739373136363031342c22646f6d223a226578616d706c655f74656c65636f6d222c22616363223a2261646d696e222c22756964223a2230316131643466322d353735362d376438372d616631322d616162643434613730616339222c22737263223a226578616d706c655f74656c65636f6d222c227473223a313739343537343031347d5d01005c260500000000016e7d961200",
))
# => 01040080bdebaf574c9dc2043a423acef76a4621924a405e713735ec8f21653abe3576a201017ae5b59defdf441dfd30a4b5383cba9fc63fbd21740582bf4322748a62bc9181a450dff5ff0a730ab406e142254238f848451e757dce2cd0035841155f6123025657f2d4a10100003c6578616d706c655f74656c65636f6d1461646d696e0004080d08013c6578616d706c655f74656c65636f6d1461646d696e0d0234636f6e747269627574696f6e730d0149035b7b226964223a223230332e302e3131332e392d3230332e302e3131332e39222c226674223a332c226f7267223a225345222c22647374223a224742222c22737473223a302c226564223a313739373136363031342c22646f6d223a226578616d706c655f74656c65636f6d222c22616363223a2261646d696e222c22756964223a2230316131643466322d353735362d376438372d616631322d616162643434613730616339222c22737263223a226578616d706c655f74656c65636f6d222c227473223a313739343537343031347d5d01005c260500000000016e7d961200
js
// npm install @noble/hashes
import { createPrivateKey, sign } from 'node:crypto'
import { blake2b } from '@noble/hashes/blake2.js'

// DER header that turns 32 raw key bytes into a PKCS#8 Ed25519 key
const PKCS8_ED25519_PREFIX = '302e020100300506032b657004220420'

/**
 * @param {string} publicKeyHex - signing public key, 64 hex characters
 * @param {string} privateKeyHex - signing private key; a 128-character key is
 *                                 the private key followed by the public key
 * @param {string} transactionHex - the assembled transaction
 * @returns {string} - the signed transaction hex
 */
function signTransaction(publicKeyHex, privateKeyHex, transactionHex) {
  if (!transactionHex.startsWith('0100')) {
    throw new Error('not an assembled transaction')
  }
  const payload = Buffer.from(transactionHex.slice(4), 'hex')

  const key = createPrivateKey({
    key: Buffer.from(PKCS8_ED25519_PREFIX + privateKeyHex.slice(0, 64), 'hex'),
    format: 'der',
    type: 'pkcs8'
  })

  const digest = Buffer.from(blake2b(payload, { dkLen: 32 }))
  digest[31] |= 1
  const signature = sign(null, digest, key).toString('hex')

  return '0104' + '0080' + publicKeyHex + '0101' + signature + payload.toString('hex')
}

console.log(
  signTransaction(
    'bdebaf574c9dc2043a423acef76a4621924a405e713735ec8f21653abe3576a2',
    'c3396eb8c9acd64659cc2a258415b8aebd45abea4a5f02cb1163ee20956d9a11',
    '01005657f2d4a10100003c6578616d706c655f74656c65636f6d1461646d696e0004080d08013c6578616d706c655f74656c65636f6d1461646d696e0d0234636f6e747269627574696f6e730d0149035b7b226964223a223230332e302e3131332e392d3230332e302e3131332e39222c226674223a332c226f7267223a225345222c22647374223a224742222c22737473223a302c226564223a313739373136363031342c22646f6d223a226578616d706c655f74656c65636f6d222c22616363223a2261646d696e222c22756964223a2230316131643466322d353735362d376438372d616631322d616162643434613730616339222c22737263223a226578616d706c655f74656c65636f6d222c227473223a313739343537343031347d5d01005c260500000000016e7d961200'
  )
)
// => 01040080bdebaf574c9dc2043a423acef76a4621924a405e713735ec8f21653abe3576a201017ae5b59defdf441dfd30a4b5383cba9fc63fbd21740582bf4322748a62bc9181a450dff5ff0a730ab406e142254238f848451e757dce2cd0035841155f6123025657f2d4a10100003c6578616d706c655f74656c65636f6d1461646d696e0004080d08013c6578616d706c655f74656c65636f6d1461646d696e0d0234636f6e747269627574696f6e730d0149035b7b226964223a223230332e302e3131332e392d3230332e302e3131332e39222c226674223a332c226f7267223a225345222c22647374223a224742222c22737473223a302c226564223a313739373136363031342c22646f6d223a226578616d706c655f74656c65636f6d222c22616363223a2261646d696e222c22756964223a2230316131643466322d353735362d376438372d616631322d616162643434613730616339222c22737263223a226578616d706c655f74656c65636f6d222c227473223a313739343537343031347d5d01005c260500000000016e7d961200
kotlin
// build.gradle:
//   repositories {
//       mavenCentral()
//       maven { url "https://jitpack.io" }
//   }
//   dependencies {
//       implementation "com.github.hyperledger.iroha-java:client:1cd813f"
//   }

// Your package value:
package something

// Import dependencies:
import jp.co.soramitsu.iroha2.appendSignatures
import jp.co.soramitsu.iroha2.generated.SignedTransaction
import jp.co.soramitsu.iroha2.keyPairFromHex
import net.i2p.crypto.eddsa.spec.EdDSANamedCurveTable
import org.bouncycastle.util.encoders.Hex

// Example transaction Hex string:
// transactionHex = "01005657f2d4a10100003c6578616d706c655f74656c65636f6d1461646d696e0004080d08013c6578616d706c655f74656c65636f6d1461646d696e0d0234636f6e747269627574696f6e730d0149035b7b226964223a223230332e302e3131332e392d3230332e302e3131332e39222c226674223a332c226f7267223a225345222c22647374223a224742222c22737473223a302c226564223a313739373136363031342c22646f6d223a226578616d706c655f74656c65636f6d222c22616363223a2261646d696e222c22756964223a2230316131643466322d353735362d376438372d616631322d616162643434613730616339222c22737263223a226578616d706c655f74656c65636f6d222c227473223a313739343537343031347d5d01005c260500000000016e7d961200"
fun decodeSignEncode(transactionHex: String): String {
    // Example ed25519 public key:
    val publicKey = "bdebaf574c9dc2043a423acef76a4621924a405e713735ec8f21653abe3576a2"

    // Example ed25519 private key:
    // Note: this SDK takes the 64-character private key, not the 128-character form.
    val privateKey = "c3396eb8c9acd64659cc2a258415b8aebd45abea4a5f02cb1163ee20956d9a11"

    // Obtain 'keyPair' from the public and private keys of the signing key pair:
    val keyPair = keyPairFromHex(
        publicKey,
        privateKey,
        EdDSANamedCurveTable.getByName(EdDSANamedCurveTable.ED_25519)
    )

    // Decode the transaction:
    val transaction: ByteArray = try {
        Hex.decode(transactionHex)
    } catch (e: IllegalArgumentException) {
        println("Could not decode transaction from hex format: $e")
        throw e
    }
    val decodedTransaction = transaction.let { SignedTransaction.decode(it) }

    // Sign the transaction:
    val signedTransaction = decodedTransaction.appendSignatures(keyPair)

    // Re-encode the transaction:
    val encoded = signedTransaction.let { SignedTransaction.encode(it) }
    val encodedHex = Hex.toHexString(encoded)

    // Use the value wherever needed further:
    println("Signed transaction (Hex): $encodedHex")
    return encodedHex
}

The Python and Node.js examples need no SDK. The Kotlin/Java example uses an open-source SDK that decodes the transaction, appends the signature and encodes it again. All three return the same Hex string.

Test vector ​

Before you call the API, check your implementation against these values. The key pair is a test key made for this page, not the key of a real account:

FieldValue
Signing private key (test key)c3396eb8c9acd64659cc2a258415b8aebd45abea4a5f02cb1163ee20956d9a11
Signing public key (test key)bdebaf574c9dc2043a423acef76a4621924a405e713735ec8f21653abe3576a2
Digest after the last-byte rule6078b56b4e223896188ddbdad87e60b527d6816203cc2686e85f558447f645c1
Signature7ae5b59defdf441dfd30a4b5383cba9fc63fbd21740582bf4322748a62bc9181a450dff5ff0a730ab406e142254238f848451e757dce2cd0035841155f612302

The assembled transaction:

text
01005657f2d4a10100003c6578616d706c655f74656c65636f6d1461646d696e0004080d08013c6578616d706c655f74656c65636f6d1461646d696e0d0234636f6e747269627574696f6e730d0149035b7b226964223a223230332e302e3131332e392d3230332e302e3131332e39222c226674223a332c226f7267223a225345222c22647374223a224742222c22737473223a302c226564223a313739373136363031342c22646f6d223a226578616d706c655f74656c65636f6d222c22616363223a2261646d696e222c22756964223a2230316131643466322d353735362d376438372d616631322d616162643434613730616339222c22737263223a226578616d706c655f74656c65636f6d222c227473223a313739343537343031347d5d01005c260500000000016e7d961200

The signed transaction:

text
01040080bdebaf574c9dc2043a423acef76a4621924a405e713735ec8f21653abe3576a201017ae5b59defdf441dfd30a4b5383cba9fc63fbd21740582bf4322748a62bc9181a450dff5ff0a730ab406e142254238f848451e757dce2cd0035841155f6123025657f2d4a10100003c6578616d706c655f74656c65636f6d1461646d696e0004080d08013c6578616d706c655f74656c65636f6d1461646d696e0d0234636f6e747269627574696f6e730d0149035b7b226964223a223230332e302e3131332e392d3230332e302e3131332e39222c226674223a332c226f7267223a225345222c22647374223a224742222c22737473223a302c226564223a313739373136363031342c22646f6d223a226578616d706c655f74656c65636f6d222c22616363223a2261646d696e222c22756964223a2230316131643466322d353735362d376438372d616631322d616162643434613730616339222c22737263223a226578616d706c655f74656c65636f6d222c227473223a313739343537343031347d5d01005c260500000000016e7d961200

Ed25519 signatures are deterministic, so a correct implementation returns exactly this signed transaction.

Rejected requests ​

A body that the Exchange cannot read as a transaction is rejected with a 400 response (code 15, InvalidTransaction, "Transaction is not readable"). Check the following:

  • The body is the Hex string alone, sent as plain text. It is not wrapped in quotes or in a JSON object.
  • The Hex string has no 0x prefix.
  • The payload is sent exactly as it was assembled.