lock upgrade + more API docs