docs: update jsdoc

Author: solidsnakedev

packages/evolution/src/core/SignData.ts

@@ -1,15 +1,8 @@
 /**
- * COSE (RFC 8152) message signing for Cardano (CIP-0030).
+ * COSE (RFC 8152) message signing for Cardano.
  *
- * This module provides a TypeScript implementation of @emurgo/cardano-message-signing-nodejs,
- * offering the complete CSL message signing API surface including:
- * - COSESign1Builder: Builder for creating COSE_Sign1 structures
- * - COSESign1: Signed message representation
- * - COSEKey: COSE key representation
- * - Headers: Protected and unprotected headers
- * - HeaderMap: Map of header labels to values
- * - Label: Header label representation
- * - EdDSA25519Key: Ed25519 key operations
+ * Implements CIP-30 wallet API and CIP-8 message signing using COSE_Sign1 structures.
+ * Compatible with all major Cardano wallets.
  *
  * @since 2.0.0
  * @category Message Signing
@@ -568,7 +561,7 @@ export class COSEKey extends Schema.Class<COSEKey>("COSEKey")({
 
 /**
  * CBOR bytes transformation schema for COSEKey.
- * Encodes COSEKey as a CBOR Map compatible with CSL/lucid-evolution.
+ * Encodes COSEKey as a CBOR Map compatible with CSL.
  *
  * @since 2.0.0
  * @category Schemas
@@ -1076,13 +1069,17 @@ export const coseSign1BuilderNew = (
 /**
  * Payload type - raw binary data to be signed.
  *
+ * The payload is NOT pre-hashed before signing (per CIP-8).
+ *
  * @since 2.0.0
  * @category Types
  */
 export type Payload = Uint8Array
 
 /**
- * Signed message result.
+ * Signed message result (CIP-30 DataSignature format).
+ *
+ * Contains CBOR-encoded COSE_Sign1 (signature) and COSE_Key (public key).
  *
  * @since 2.0.0
  * @category Types
@@ -1094,7 +1091,12 @@ export type SignedMessage = {
 
 /**
  * Sign data with a private key using COSE_Sign1.
- * Compatible with lucid-evolution's sign_data implementation.
+ *
+ * Implements CIP-30 `api.signData()` specification. Creates a COSE_Sign1 structure with:
+ * - Protected headers: algorithm (EdDSA), address
+ * - Unprotected headers: hashed (false)
+ * - Payload: NOT pre-hashed
+ * - Returns CBOR-encoded COSE_Sign1 and COSE_Key
  *
  * @since 2.0.0
  * @category API
@@ -1104,11 +1106,11 @@ export const signData = (
   payload: Payload,
   privateKey: PrivateKey.PrivateKey
 ): SignedMessage => {
-  // Create headers with algorithm and address (in protected headers like lucid-evolution)
+  // Create headers with algorithm and address in protected headers
   const protectedHeaders = headerMapNew()
     .setAlgorithmId(AlgorithmId.EdDSA)
     .setHeader(labelFromText("address"), Bytes.fromHex(addressHex))
-  // Add "hashed": false to unprotected headers (lucid-evolution compatibility)
+  // Add "hashed": false to unprotected headers
   const unprotectedHeaders = headerMapNew().setHeader(labelFromText("hashed"), false)
   const headers = headersNew(protectedHeaders, unprotectedHeaders)
 
@@ -1127,7 +1129,7 @@ export const signData = (
   // Encode to CBOR bytes
   const signedBytes = Schema.encodeSync(COSESign1FromCBORBytes())(coseSign1)
 
-  // Build COSEKey compatible with lucid-evolution
+  // Build COSEKey
   const vkey = VKey.fromPrivateKey(privateKey)
   const ed25519Key = new EdDSA25519Key({ privateKey: undefined, publicKey: vkey }, { disableValidation: true })
   const coseKey = ed25519Key.build()
@@ -1141,7 +1143,13 @@ export const signData = (
 
 /**
  * Verify a COSE_Sign1 signed message.
- * Compatible with lucid-evolution's verifyData implementation.
+ *
+ * Validates CIP-30 signatures by verifying:
+ * - Payload matches signed data
+ * - Address matches protected headers
+ * - Algorithm is EdDSA
+ * - Public key hash matches provided key hash
+ * - Ed25519 signature is cryptographically valid
  *
  * @since 2.0.0
  * @category API