Twin Ownership Transfer

[sameh-farouk]

Description

Introduces a simple, two-party twin ownership transfer flow:

• Current owner initiates a transfer to a specified new account.
• New account accepts to finalize the transfer.
• The current owner can cancel a pending request.
• On acceptance, any reserved balance associated with the twin’s owner is moved to the new owner, and ownership/indexes are updated.

Key behavior

• One pending transfer per twin at a time (no separate status field; “pending” is implied by existence of a request).
• The owner can cancel a pending transfer at any moment.
• Acceptance completes the transfer and clears the request.
• Defensive checks ensure ownership/index consistency before changes.
• No expiry logic atm; each request records created_at for potential future cleanup.

Events

• Requested, Transferred, and Canceled events all include: request_id, twin_id, from, to.

Compatibility and migration

• Additive storage; existing data remains valid.
• No runtime storage migration required.

Security considerations

• Two-party consent: both “from” (initiation/cancel) and “to” (accept) must participate.
• “To” must meet prerequisites (terms accepted, no existing twin).
• Ownership and accounting are updated atomically.

Testing and documentation

• Unit tests updated to cover request, accept, cancel, and balance movement.
• Documentation updated to describe the new flow, events, from/to semantics, and prerequisites.

Related Issues:

• Migration of workloads #1061

Checklist:

• My change requires a change to the documentation and I have updated it accordingly
• I have added tests to cover my changes.
• My commits follow this conventional commits guide.