Files
iam/internal/did/abi.go
zeekayandHanzo Dev f978786402 Anchor the identity IAM already asserts in the DID registry
A deployment that names a registry, a chain, an RPC and a KMS-mounted
controller key gets the account's DID written on chain when a wallet is
linked: the document if the registry does not hold one, a service entry
naming the issuer that asserts the identity and the subject at it, and the
wallet as a verification method. A deployment that names none links wallets
and mints the same `did` claim, because the claim is derived from the subject
and owes the registry nothing. Anchoring publishes the fact; it does not
create it.

THE STORE IS THE SOURCE OF TRUTH, the registry is a projection. Every write
happens after the link commits and outside its transaction, so a chain that
is slow, forked or gone cannot fail a sign-in or leave a wallet half-linked.
The cost is that a failed anchor is not retried: the document catches up the
next time that person links a wallet. Convergence, if a deployment wants it,
reconciles from the store — which holds every binding — rather than making a
login wait on a block.

Only a NEW binding is anchored, which is why verify now returns the wallet it
bound rather than only the user. Signing in with a wallet already on file
changes nothing, and asking "is there a row" afterwards cannot tell the two
apart because the row is there either way; a flag would have answered, but
the wallet also carries the CANONICAL address the verifier settled on instead
of the spelling the client claimed.

Four settings, all of them or none — a half-named registry is a mistake, not
a choice, so it is refused rather than degrading into the off state with an
operator left wondering why nothing is written. There is deliberately no
default contract address: the one recorded for this contract in lux/standard
holds no code on any live Lux chain and names an AMM router on another, so a
default would have pointed every deployment at it. The key is a FILE, never
an inline value, because the estate has one secret path — KMS -> KMSSecret ->
Secret -> mounted material, the same path the registry signing key and
provision's credentials already read. A key in the environment is a plaintext
secret in a pod spec.

Two things worth stating plainly rather than discovering in production. The
contract splits its authority — createDIDFor is registrar-only while
addVerificationMethod and addService are controller-only — so one key can do
all three only by creating documents controlled by itself, and these
documents are therefore not self-sovereign. Handing control to the person
ends IAM's ability to keep the document in step, and no registrar override
gets it back. And only EVM wallets become verification methods: the
registry's struct types an account as an `address` plus a bytes32, which fits
a secp256k1 account and nothing else. Other chains link normally, appear in
the claim and count as a credential; packing a base58 address into an
`address` field would be inventing an encoding no resolver reads.

Selectors are derived from the canonical signature strings at init, never
pasted. A four-byte constant is a value nobody can check by reading it, and a
transposed digit still encodes, still sends, and reverts on chain as an
unknown method — which looks exactly like a permissions failure. The registry
is also asked once for its OWN method string and refuses to write if it
disagrees with ours, because documents registered under a name no token's
claim matches are worse than no documents.

Co-authored-by: Hanzo Dev <[email protected]>
2026-09-04 00:42:52 -07:00

173 lines
6.5 KiB
Go

// Copyright 2026 Hanzo AI, Inc.
// SPDX-License-Identifier: MIT OR Apache-2.0
package did
import (
"math/big"
luxcrypto "github.com/luxfi/crypto"
"github.com/luxfi/crypto/common"
)
// Solidity call encoding for the four DIDRegistry methods this package uses.
//
// Hand-written, and small enough to read in one sitting, because the alternative
// is a generated binding — which would pull an EVM client library into a service
// whose job is issuing tokens. Four calls, three of which take one string and one
// struct, do not pay for that.
//
// SELECTORS ARE DERIVED, NEVER PASTED. Each is keccak256 of the canonical
// signature string below, computed at init. A pasted four-byte constant is a
// value nobody can check by reading it: transpose two hex digits and the call
// still encodes, still sends, and reverts on chain as an unknown method — which
// looks exactly like a permissions failure. The signature string is the thing a
// reader can compare against the .sol file.
// The canonical signatures, verbatim from contracts/identity/DIDRegistry.sol.
// A tuple argument is spelled by its component types in declaration order, which
// is what Solidity hashes: VerificationMethod is
// (bytes32 id, uint8 methodType, address controller, bytes publicKeyMultibase,
// bytes32 blockchainAccountId) and Service is
// (bytes32 id, uint8 serviceType, string endpoint, bytes data).
const (
sigCreateDIDFor = "createDIDFor(string,address)"
sigAddVerification = "addVerificationMethod(string,(bytes32,uint8,address,bytes,bytes32))"
sigAddService = "addService(string,(bytes32,uint8,string,bytes))"
sigDIDExists = "didExists(string)"
sigMethod = "method()"
wordLen = 32
verificationFieldCount = 5
serviceFieldCount = 4
)
// selector is the four-byte function selector of a canonical signature.
func selector(sig string) []byte { return luxcrypto.Keccak256([]byte(sig))[:4] }
// createDIDFor encodes createDIDFor(identifier, controller). The identifier is
// the method-specific-id — the registry concatenates "did:<method>:" onto it
// itself, so the FULL DID must not be passed here.
func createDIDFor(identifier string, controller common.Address) []byte {
out := selector(sigCreateDIDFor)
// Head: two words — the offset to the string tail, then the address.
out = append(out, word(big.NewInt(2*wordLen))...)
out = append(out, addressWord(controller)...)
return append(out, bytesTail([]byte(identifier))...)
}
// addVerificationMethod encodes addVerificationMethod(did, method). did is the
// FULL "did:lux:…" string, because the registry keys every document by
// keccak256 of it.
func addVerificationMethod(did string, m verification) []byte {
tuple := m.encode()
out := selector(sigAddVerification)
// Head: offset to the did string, then offset to the tuple. Both arguments
// are dynamic (the tuple contains `bytes`), so both are references.
out = append(out, word(big.NewInt(2*wordLen))...)
didTail := bytesTail([]byte(did))
out = append(out, word(big.NewInt(int64(2*wordLen+len(didTail))))...)
out = append(out, didTail...)
return append(out, tuple...)
}
// addService encodes addService(did, service).
func addService(did string, s service) []byte {
tuple := s.encode()
out := selector(sigAddService)
out = append(out, word(big.NewInt(2*wordLen))...)
didTail := bytesTail([]byte(did))
out = append(out, word(big.NewInt(int64(2*wordLen+len(didTail))))...)
out = append(out, didTail...)
return append(out, tuple...)
}
// didExists encodes the view call that reports whether a document is already
// registered. It is what keeps a re-link from re-creating a DID the registry
// would revert on.
func didExists(did string) []byte {
out := selector(sigDIDExists)
out = append(out, word(big.NewInt(wordLen))...)
return append(out, bytesTail([]byte(did))...)
}
// registryMethod encodes the view call returning the registry's OWN method
// string. See Registry.check for why it is asked.
func registryMethod() []byte { return selector(sigMethod) }
// verification is the VerificationMethod struct the registry stores.
type verification struct {
id [32]byte
methodType uint8
controller common.Address
publicKey []byte
accountHash [32]byte
}
// encode lays the struct out as a dynamic ABI tuple: four head words (the
// `bytes` field carries an offset instead of a value) followed by the bytes
// tail. Offsets inside a tuple are relative to the TUPLE's own start, not to
// the call data's.
func (v verification) encode() []byte {
out := make([]byte, 0, verificationFieldCount*wordLen+wordLen+len(v.publicKey))
out = append(out, v.id[:]...)
out = append(out, word(big.NewInt(int64(v.methodType)))...)
out = append(out, addressWord(v.controller)...)
out = append(out, word(big.NewInt(verificationFieldCount*wordLen))...)
out = append(out, v.accountHash[:]...)
return append(out, bytesTail(v.publicKey)...)
}
// service is the Service struct the registry stores.
type service struct {
id [32]byte
serviceType uint8
endpoint string
data []byte
}
// encode lays the struct out as a dynamic ABI tuple. Two of its four fields are
// dynamic, so the second offset depends on the first field's encoded length.
func (s service) encode() []byte {
endpoint := bytesTail([]byte(s.endpoint))
out := make([]byte, 0, serviceFieldCount*wordLen+len(endpoint)+wordLen+len(s.data))
out = append(out, s.id[:]...)
out = append(out, word(big.NewInt(int64(s.serviceType)))...)
out = append(out, word(big.NewInt(serviceFieldCount*wordLen))...)
out = append(out, word(big.NewInt(int64(serviceFieldCount*wordLen+len(endpoint))))...)
out = append(out, endpoint...)
return append(out, bytesTail(s.data)...)
}
// bytesTail encodes a dynamic `bytes`/`string` value: its length, then its
// content right-padded to a whole number of words.
func bytesTail(b []byte) []byte {
out := word(big.NewInt(int64(len(b))))
out = append(out, b...)
if pad := (wordLen - len(b)%wordLen) % wordLen; pad > 0 {
out = append(out, make([]byte, pad)...)
}
return out
}
// word left-pads an unsigned integer into one 32-byte ABI word.
func word(i *big.Int) []byte {
out := make([]byte, wordLen)
i.FillBytes(out)
return out
}
// addressWord left-pads a 20-byte address into one 32-byte ABI word.
func addressWord(a common.Address) []byte {
out := make([]byte, wordLen)
copy(out[wordLen-common.AddressLength:], a[:])
return out
}
// hash32 is keccak256 as a fixed array, the shape the registry's bytes32 ids
// take.
func hash32(s string) [32]byte {
var out [32]byte
copy(out[:], luxcrypto.Keccak256([]byte(s)))
return out
}