sRFC-35 - Address/Domain Association Specification
Summary
Solana addresses can be publicly linked to domain names using DNS TXT records or a well-known file. This allows for applications and services (like wallets, exchanges, and infrastructure providers) to easily validate if a company is associated (or denounce associations) with a token, program, or other Solana address that may be using their trademarks.
Background
As more companies and brands interact with permissionless blockchains (like Solana), having simple mechanisms for them to publicly associate (or denounce association) with onchain assets will enable verifiable trust for these groups and the broader Solana ecosystem.
Utilizing DNS TXT records or a well-known file on a website, domain administrators can associate blockchain addresses for tokens, programs (smart contracts), or other Solana addresses. This allows other companies and products to validate the original company’s connection to said Solana address.
Example use cases:
- A brand issues a Solana token with their website listed in the token’s metadata. They add a DNS record to store the token’s Mint address on their DNS records. Popular token list providers, like Jupiter and CoinGecko, can fetch, parse, and validate the token in question was created by the brand. Enabling their verification processes to be more efficient while also enabling the token issuer to get easier access to liquidity at launch.
- A company deploys a Solana program (smart contract) onchain. The company adds the DNS record associating the program address to their website. The program’s security.txt information includes the company’s contact information and website for security researchers to responsibly report vulnerabilities.
Note: This practice of domain verification through DNS records is already a common practice in the broader tech industry. For example, connecting your website to the Google Cloud Console or verifying domain ownership for various AWS products.
Specification
To associate a Solana address with a domain name, the domain administrator should create a DNS TXT record on their registrar or a solana.txt file on their website’s .well-known directory to store the “association records” using any of the applicable well-known tags listed below.
Association through DNS TXT records
(most recommended)
Domain administrators can add one or many DNS TXT records, each storing a single “association record”.
Note: DNS TXT records have a few limitations that are not expected to be an issue for this specification, but worth noting in the event they are. If either of these are a concern, see solana.txt below for another option:
- TXT records are limited to 255 characters, per the DNS spec. A typical “association record” per this spec should normally be a max of <80 characters.
- Some domain registrars and platforms, like Google, recommend no more than 49 TXT records due to this being the max supported by domains themselves.
Association through the solana.txt file
Due to company policy or technical limitations, it is possible that some administrators are unable to create additional DNS TXT records for their domain. In such cases, address association can be accomplished by creating a solana.txt file and storing it in the .well-known directory (see RFC-8615).
For example:
- Domain:
example.com - Location of the association file:
example.com/.well-known/solana.txt
The solana.txt file should only store one “association record” per line to allow efficient parsing by record validators.
Note: It is highly recommended that administrators allow frontend applications to access their solana.txt by setting correct CORS headers. This will help ensure anyone that would like to can validate the address/domain association.
Association records
A single entry in the DNS TXT or line in the solana.txt file is called an “association record”.
Each entry should store the UTF-8 string of a space separated list of tag-value pairs (using the well-known tags supported below).
Each association record should contain a single “address tag” and a single Solana address as a base58 encoded string, followed by any additional qualifier tag-value pairs (deny, allow, network, etc).
If a domain or website wants to deny all association with all Solana addresses (tokens, programs, etc), they can create add a single “deny all” association record of solana-address=denyall. This special record takes precedence over all other association records.
Well-known tags
Each association record should contain a single “address tag” that best describes the purpose of the Solana address
solana-mint-address- associates a token’s Mint address to the domain.solana-program-address- associates a program address to the domain.solana-address- associates any other Solana address with a domain (such as a verified signer, program deployer, or other authority).
In addition to the blockchain specific tags above, the following generic tags (qualifiers) are also supported to add amplifying information about the associated relationship:
deny(optional) - Explicitly deny the association of the address with the domain.allow(optional) - Explicitly allow the association of the address with the domain.network(optional) - Define the Solana or SVM network the address is used on. This value can be either a Solana network moniker (mainnet,devnet,testnet) or the genesis hash of a SVM network, as a base58 string. If not set, defaults to Solana mainnet.
Qualifier notes:
- The value of a qualifier should be the case-insensitive string or numeric equivalent for a boolean value (i.e.
allow=trueandallow=1set “allow” to the booleantrue) - Records should not contain both
allowanddeny - When no
allowordenyis set, defaults toallow=truesignifying the domain is in fact associated with the address.
So an association record would resemble the following examples:
# token on mainnet
solana-mint-address=EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v
# token on devnet
solana-mint-address=EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v allow=1 network=devnet
# generic address
solana-address=EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v deny=1 network=devnet
solana-mint-address
This association record’s “address tag”-value pair should be used to store a token’s Mint address as a base58 string:
- To allow association:
solana-mint-address=EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v
- To deny association:
solana-mint-address=EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v deny=1
Example: To associate the USDC token with a domain, create an association record with a value of:
solana-mint-address=EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v
Which is also the same as:
solana-mint-address=EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v allow=truesolana-mint-address=EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v allow=1solana-mint-address=EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v network=mainnet allow=1
To deny association of a token’s mint:
solana-mint-address=EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v deny=1
Which is also the same as:
solana-mint-address=EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v deny=truesolana-mint-address=EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v network=mainnet deny=true
solana-program-address
This association record’s “address tag”-value pair should be used to store a program’s address as a base58 string:
- To allow association:
solana-program-address=SMPLecH534NA9acpos4G6x7uf3LWbCAwZQE9e8ZekMu
- To deny association:
solana-program-address=SMPLecH534NA9acpos4G6x7uf3LWbCAwZQE9e8ZekMu deny=1
solana-address
This association record’s “address tag”-value pair should be used to store any address as a base58 string. This is considered a fallback address tag and should only be used when the other, more explicit tags do not fit the address’ use case.
- To allow association:
solana-address=nicktrLHhYzLmoVbuZQzHUTicd2sfP571orwo9jfc8c
- To deny association:
solana-address=nicktrLHhYzLmoVbuZQzHUTicd2sfP571orwo9jfc8c deny=1
Linking a domain within onchain information
If there is a domain referenced in onchain-linked data, including the contents of referenced offchain JSON files, an association check should be performed to verify a connection to the brand/company’s linked domain.
When wallets, token lists, block explorers, and other applications are presenting information about onchain data (i.e. url for a token’s image, primary media file, or url for its additional offchain metadata file), they should also present the address/domain association status when available.
These “association validators” can poll the DNS records (or solana.txt file) for the domain in question and validate if the domain and onchain information point to each other. If they do and are in the “allow” state, the ecosystem can consider these associated. Otherwise, not-associated and handled as such.
Listed below are some of the most commonly used standards where domains are referenced in onchain-linked data. As future metadata standards develop and are adopted, they should also consider and adopt similar pattern. And therefore be supported by this specification.
- Metaplex’s Fungible and Non-fungible asset standards - contain support for the
image,external_url, andanimation_urlfields - SPL Token metadata interface - contain support for the a
urifield that links to offchain metadata file, normally as a JSON format. This JSON file commonly follows one of Metaplex’s standards. - security.txt - contain the
project_urlfield and other domain related fields
Security considerations
Permissioned access. Modifying DNS records or uploading the solana.txt file require permissioned access to a domain and its resources. If an attacker was able to gain permissioned access, they could modify the association records. Due to this not being an attack vector being specific to this specification, it is consider out of scope. Domain administrators should ensue they have strong security practices to prevent this.
Homograph attacks. With the use of domain names to validate if an addresses is associated, attackers will likely attempt to perform these letter substitution attacks on domains/users.
- Since the address/domain association checks will be performed by code and automated systems, so it is not a concern there.
- However, when the domain names are presented to users they could become fooled by the letter substitutions. As such, applications should be diligent in helping to minimize/prevent fake domains by performing mitigation steps. See examples here.
DNS cache poisoning. Attackers could attempt to poison the DNS cache for servers and users attempting to get the association records from a domain. If an attacker is successful in this type of attack, association validators could be fooled into validation the attacker-inserted association. Resulting in applications and users falsely thinking the attacker’s address is truly associated with the domain.
- DNS cache poisoning can be prevented by domain administrators enabling and using DNSSEC. It is strongly recommend that administrators enable DNSSEC and that automated validation processes check for DNSSEC enabled domains.
