Signed and encrypted messages
Not every signature needs a transaction. A signed message proves that you hold a key without moving any money and without paying a fee; an encrypted message lets only its recipient read it. This page covers both, and two related signatures the node API accepts.
Proving that you control an address
A website that wants to know that you control a ZooBC address sends you a random challenge. You sign it with zbc-cli sign-message, or with the same function in any port of the public command-line tools, and the site checks the signature against your address. For a native ZBC_ address the address is the public key itself, so nothing else is needed. Sending a payment would also prove control, but that is a transaction and costs a fee. Never give anyone your private key instead.
The scheme is called ZBC-MSG-v2. It signs, with Ed25519:
SHA3-256("ZBC-MSG-v2" ‖ genesis hash ‖ message)Two parts of that digest matter:
- The tag. Transactions are signed under a different tag, "ZBC-TX". A message signature can therefore never be valid as a transaction, and a transaction signature never as a message.
- The genesis hash. It ties the signature to one network: a message signed for devnet never verifies on testnet or mainnet (chain-bound signatures).
For a transition period, the tools' verify-message also accepts the older form without a chain, ZBC-MSG-v1 (SHA3-256 of "ZBC-MSG" and the message). The period ends at a cut-off time fixed in the tools; after it, only ZBC-MSG-v2 verifies.
Message signing is a convention of the public tools and of the services that adopt it, not a chain feature. Nothing is stored on the chain, and nodes have no endpoint for it.
Encrypted messages
Every transaction can carry a message (transaction envelope). A plain message is at most 256 bytes. An encrypted one starts with the marker "ZBE1", followed by a libsodium sealed box addressed to the recipient's key, which only the recipient's private key can open. An encrypted message may be up to 320 bytes, which leaves room for at most 268 bytes of text.
Only the message is encrypted. The rest of the transaction, such as its sender, recipient and amount, stays as public as any other.
Signed API requests
Most of the node API is open reads, and a transaction needs no API key because it carries its own signature. Where a request itself must be signed, the signature is Ed25519 over the text METHOD:PATH:TIMESTAMP:BODY, valid for 300 seconds. A client that fails 20 signed authentications within 5 minutes is locked out for 300 seconds.
Cancelling a pending transaction
A transaction that is waiting in a node's pool can be withdrawn from that node with DELETE /api/v1/transactions/pending/ followed by its hash. The request carries a signature over:
SHA3-256("ZBC-CANCEL" ‖ genesis hash ‖ transaction hash)It removes the copy only from that node's pool. Other nodes that already hold the transaction may still include it in a block, so a cancellation is a request, not a guarantee.