importWallet
Bring existing key material in through an authorized secure flow.
Status
Proposed target SDK behavior for implementation. It is not an available SDK, custody protocol, or supported-format claim.
Business action#
Bring one existing network-scoped signing key/address into managed wallet operation through an approved encrypted import flow.
Proposed call#
importWallet(
input: ImportWalletInput,
options?: CallOptions,
): Promise<Operation<ImportWalletResult>>
TypeScript uses requestId, network, expectedAddress, owner, encryptedImportPackage, and optional authorization. The encrypted package is an explicit byte-safe DTO, not text with an implicit encoding.
async def import_wallet(
input: ImportWalletInput,
*,
options: CallOptions | None = None,
) -> Operation[ImportWalletResult]: ...
Python uses request_id, expected_address and encrypted_import_package. Byte input is explicit and is never accepted through an ambiguous text conversion.
ImportWallet(
ctx context.Context,
input *ImportWalletInput,
) (*Operation[ImportWalletResult], error)
Go uses RequestID, ExpectedAddress and EncryptedImportPackage; the binding copies mutable byte input before retaining operation material. Cancellation after SDK dispatch requires GetOperation recovery, even when backend acceptance was not observed.
Required input: requestId, network, explicit controlMode, expected public address, mode-appropriate owner/service identity, encrypted import package and authorization. Import never infers or changes control mode.
Result and effects#
Success returns one wallet with the verified expected address, owner, rights and operation result. It does not move funds or invalidate copies held elsewhere.
The request ID binds the expected address, network, recipient context, owner and encrypted package. Same-ID/same-material replay converges; changed material conflicts. Unknown outcome is resolved with getOperation(requestId) rather than another import.
Import is not recovery from a lost device or authorization factor. Use recoverWalletAccess for that business scenario.
Security and failures#
Plaintext signing material must never enter ordinary public method results, application state, request logging, error messages, examples or telemetry. A browser import is allowed only through an accepted secure device/recipient flow; it is not automatic custody selection. Wrong recipient context, address mismatch, malformed package, expiry, denial or insufficient agreement activates no wallet. The SDK may hide preparation mechanics but cannot claim support for a format or algorithm before backend and cross-language evidence exists.
When grants are insufficient, the SDK uses the mode-appropriate owner/service handler once or returns requiresAction; it cannot do both. The response binds exact import and mode. End-user login cannot import into server treasury authority.
Acceptance#
- Positive: authorized ciphertext produces the expected network address and a readable wallet under the same request identity.
- Negative: address/context mismatch or uncertain outcome cannot create a falsely successful wallet; import cannot be presented as lost-access recovery.
See recoverWalletAccess and getOperation.