Coinbase SDK v1.31.0: Docs Typo and Key Parsing Issues for `CDP_WALLET_SECRET` and `CDP_API_KEY_SECRET`

[metatronyxAI]

Coinbase SDK v1.31.0: Docs Typo and Key Parsing Issues for CDP_WALLET_SECRET and CDP_API_KEY_SECRET

Summary

The Coinbase Developer Platform documentation (https://docs.cdp.coinbase.com/server-wallets/v2/introduction/quickstart) contains a critical typo stating that CDP_WALLET_SECRET should be a "base64 Ed25519 key," but cdp-sdk v1.31.0 requires a base64 DER EC key (approximately 184 characters, ~138 bytes decoded). Additionally, CDP_API_KEY_SECRET fails with valid PEM EC keys, requiring a base64 DER EC key instead. These issues cause parsing errors, leading to significant debugging time for developers.

Details

1. Docs Typo for CDP_WALLET_SECRET:

   • The quickstart guide specifies that CDP_WALLET_SECRET should be a "base64 Ed25519 key" (e.g., 44 chars, 32 bytes decoded, generated via pynacl).
   • However, cdp-sdk v1.31.0’s generate_wallet_jwt function (cdp/auth/utils/jwt.py:244) uses serialization.load_der_private_key with algorithm='ES256', which only supports EC keys in base64 DER format (or PEM-wrapped EC keys).
   • Using an Ed25519 key results in errors like ValueError: Could not create the EC key: Incorrect padding or ASN.1 parsing error: invalid length.
   • The portal’s 184-char EC key (e.g., starting with MIGHAg...) works correctly when used as CDP_WALLET_SECRET.

2. Parsing Issue for CDP_API_KEY_SECRET:

   • The SDK’s generate_jwt function (cdp/auth/utils/jwt.py:171) rejects valid PEM EC keys for CDP_API_KEY_SECRET, throwing ValueError: Key must be either PEM EC key or base64 Ed25519 key.
   • Using the base64 DER EC key (stripped of PEM headers, e.g., MHcCAQEE...) resolves the issue, indicating a parsing bug or undocumented requirement.

Steps to Reproduce

For CDP_WALLET_SECRET:

1. Set CDP_WALLET_SECRET to a base64 Ed25519 key (e.g., generated via pynacl: WcJafZ9O+cVAXpTN6u4sL+SC0tuojyxZRar50uxXcAI=).
2. Run CdpClient.evm.create_account() using cdp-sdk v1.31.0.
3. Observe the error: ValueError: Could not create the EC key: Incorrect padding.
4. Replace CDP_WALLET_SECRET with the portal’s 184-char EC key (base64 DER EC key, e.g., MIGHAg...).
5. Rerun the function, which succeeds and creates an EVM EOA.

For CDP_API_KEY_SECRET:

1. Set CDP_API_KEY_SECRET to a PEM EC key (e.g., -----BEGIN EC PRIVATE KEY-----MHcCAQEE...-----END EC PRIVATE KEY-----).
2. Run CdpClient.evm.get_or_create_smart_account() in cdp-sdk v1.31.0.
3. Observe the error: ValueError: Key must be either PEM EC key or base64 Ed25519 key.
4. Use the base64 DER EC key (e.g., MHcCAQEE...), which succeeds.

Expected Behavior

• The SDK should either support Ed25519 keys for CDP_WALLET_SECRET as stated in the docs or the docs should specify that CDP_WALLET_SECRET must be a base64 DER EC key.
• CDP_API_KEY_SECRET should accept valid PEM EC keys without errors, or the docs should clarify that it requires a base64 DER EC key.

Actual Behavior

• CDP_WALLET_SECRET only accepts base64 DER EC keys (or PEM-wrapped EC keys), and Ed25519 keys fail with parsing errors.
• CDP_API_KEY_SECRET rejects valid PEM EC keys, requiring base64 DER EC keys.

Environment

• SDK: cdp-sdk v1.31.0
• Python: 3.10
• OS: Ubuntu 22.04 (WSL2)
• Dependencies: pynacl 1.5.0, aiohttp, pyjwt

Suggested Fix

1. Update the documentation (https://docs.cdp.coinbase.com/server-wallets/v2/introduction/quickstart) to clarify:
   • CDP_WALLET_SECRET must be a “base64 DER EC key” (as provided by the portal).
   • CDP_API_KEY_SECRET should be a “base64 DER EC key” or confirm PEM EC key support.
2. Alternatively, add Ed25519 support to generate_wallet_jwt and generate_jwt functions in the SDK to align with the current docs.

Additional Notes

• Successfully created an EVM EOA (0xd6ea...) and funded it on Base Sepolia (tx: 0x8eb..., 0.0001 ETH) using the portal’s 184-char EC key for CDP_WALLET_SECRET.
• Encountered issues with CDP_API_KEY_SECRET when creating a smart account, resolved by using base64 DER EC key.
• The docs’ typo and parsing issues led to significant debugging time, which could be avoided with clearer instructions or fixed SDK logic.
• Reported via Coinbase’s AI agent on the docs site, but posting here for visibility to the developer community.

Contact

• GitHub: @metatronyxAI
• Email: metatronyxai@gmail.com