Esta guía está destinada a ser una referencia para desarrolladores que desean implementar compilaciones verificadas para sus programas en Solana. Cubriremos qué son las compilaciones verificadas, cómo usarlas, consideraciones especiales y mejores prácticas para garantizar la autenticidad de tu programa en la cadena.

¿Qué son las compilaciones verificadas?

Las compilaciones verificadas aseguran que el programa ejecutable que despliegas en la red de Solana coincide con el código fuente en tu repositorio. Al hacer esto, los desarrolladores y usuarios pueden tener la confianza de que el programa ejecutándose en la cadena corresponde exactamente al código base público, promoviendo la transparencia y seguridad.

El proceso de verificación implica comparar el hash del programa en la cadena con el hash del programa compilado localmente a partir del código fuente. Esto asegura que no haya discrepancias entre las dos versiones.

Aunque una compilación verificada no debe considerarse más segura que una no verificada, la compilación permite a los desarrolladores verificar por sí mismos que el código fuente coincide con lo que está desplegado en la cadena. Usando el código fuente, un desarrollador puede entonces validar qué ejecuta el código al enviar una transacción.

El proceso de compilaciones verificadas fue concebido y es mantenido por Ellipsis Labs y OtterSec. Para más detalles, sigue la guía en el repositorio original de compilaciones verificadas así como el proceso de verificación de compilación directamente en el conjunto de herramientas Anza, una vez que sea compatible.

¿Cómo funciona?

El proceso de verificación se realiza comparando el hash del programa en la cadena con el hash del programa compilado localmente a partir del código fuente. Compilas tu programa en un entorno controlado utilizando Solana Verify CLI y Docker. Esto asegura que el proceso de compilación sea determinista y consistente en diferentes sistemas. Una vez que tienes el ejecutable, puedes desplegarlo en la red Solana. Durante el proceso de compilación se crea una PDA del programa de verificación. Esta PDA contiene todos los datos necesarios para verificar el programa. La PDA contiene la dirección del programa, la URL de git, el hash del commit y los argumentos utilizados para compilar el programa.

Utilizando los datos en la PDA, cualquiera puede ejecutar el comando del programa de verificación localmente y comprobar si el programa fue compilado a partir del código fuente proporcionado. Entonces todos pueden verificar por sí mismos de manera completamente confiable o pueden ejecutar su propia API de verificación mantenida por OtterSec para proporcionar un punto de acceso fácil para que los usuarios comprueben la verificación. Ya puedes ver estas llamadas a la API siendo utilizadas en el Explorador de Solana y SolanaFM, entre otros lugares.

¿Por qué debería usar compilaciones verificadas?

El uso de compilaciones verificadas proporciona los siguientes beneficios:

• Seguridad: Garantiza que el programa que se ejecuta en la cadena coincide con el código fuente, evitando alteraciones maliciosas.

• Transparencia: Permite a otros usuarios y desarrolladores validar que el programa en la cadena es confiable comparándolo con el código base público.

• Confianza: Aumenta la confianza del usuario, ya que las compilaciones verificadas demuestran que el comportamiento de tu programa en la cadena está alineado con tu código público. Al construir programas verificables, minimizas los riesgos asociados con la ejecución de código no autorizado o malicioso. También asegura que cumples con las mejores prácticas y proporcionas a los investigadores de seguridad una forma fácil de contactarte. Además, las carteras y otras herramientas pueden permitir transacciones desde tu programa más fácilmente siempre que esté verificado.

• Descubribilidad: Cuando proporcionas una compilación verificada de tu programa, todos pueden encontrar tu código fuente, documentación, SDK del programa o IDL y también pueden contactarte fácilmente a través de GitHub en caso de que haya algún problema.

¿Cómo creo compilaciones verificadas?

Para crear compilaciones verificadas, deberás seguir estos pasos:

Resumen:

• Confirma tu código en un repositorio público
• Construye una compilación verificada en Docker
• Despliega la compilación verificada
• Verifica el programa desplegado contra la API pública

Si verificas tu programa que no está construido en un contenedor Docker, muy probablemente fallará porque las compilaciones de programas de Solana no son deterministas en diferentes sistemas.

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

cargo install solana-verify

cargo install solana-verify --version $VERSION

cargo install solana-verify --git https://github.com/Ellipsis-Labs/solana-verifiable-build --rev 13a1db2

[workspace]
members = ["program/programs/*"]
resolver = "2"

[profile.release]
overflow-checks = true
lto = "fat"
codegen-units = 1

[profile.release.build-override]
opt-level = 3
incremental = false
codegen-units = 1

[package]
name = "waffle"
version = "0.1.0"
edition = "2021"

[lib]
name = "waffle"
crate-type = ["cdylib", "lib"]

[dependencies]
solana-program = "2.1.0"

solana-verify build

solana-verify build --library-name $PROGRAM_LIB_NAME

solana-verify get-executable-hash target/deploy/$PROGRAM_LIB_NAME.so

solana program deploy -u $NETWORK_URL target/deploy/$PROGRAM_LIB_NAME.so --program-id $PROGRAM_ID --with-compute-unit-price 50000 --max-sign-attempts 100 --use-rpc

solana-verify get-program-hash -u $NETWORK_URL $PROGRAM_ID

solana-verify verify-from-repo -u $NETWORK_URL --program-id $PROGRAM_ID https://github.com/$REPO_PATH --commit-hash $COMMIT_HASH --library-name $PROGRAM_LIB_NAME --mount-path $MOUNT_PATH

solana-verify verify-from-repo --remote -um --program-id PhoeNiXZ8ByJGLkxNfZRnkUfjvmuYqLR89jjFHGqdXY https://github.com/Ellipsis-Labs/phoenix-v1

solana-verify remote submit-job --program-id <program-id> --uploader <address>

solana-verify remote get-job-status --job-id <job-id>

Cómo verificar tu programa cuando está controlado por una multifirma como Squads

Para que la verificación remota funcione, necesitas escribir los datos de verificación en un PDA firmado por la autoridad del programa. Si tu programa está controlado por una multifirma, puedes exportar esta transacción de escritura PDA y enviarla a través de Squads Protocol u otra solución de multifirma de tu elección.

solana-verify build

solana config set --url "PayedMainnetRPCAddress" // the public endpoint will be rate limited too much
solana program deploy target/deploy/verify_squads.so

solana-verify verify-from-repo https://github.com/solana-developers/verify-squads --program-id 6XBGfP17P3KQAKoJb2s5M5fR4aFTXzPeuC1af2GYkvhD

solana-verify export-pda-tx https://github.com/solana-developers/verify-squads --program-id 6XBGfP17P3KQAKoJb2s5M5fR4aFTXzPeuC1af2GYkvhD --uploader <your program authority> --encoding base58 --compute-unit-price 0

P6vBfcPaaXb8fZoT3NBAYEcdtEj7tubA1k2gBxmFKZ3UWF5YyrmDMFTvLKALCJoUuRsPAjMckudYruCu3eeWQtuDrFbEMLxLFutnKXac974fnkMivcwUdY66VLjbxQT6ATmcy7F4hBtz1G4P1h6iBJLhb8WtrtgY3i4qq45MUEb7RjuMEfUFXKrNgPdGxkz5xvMHq3dxKRcpmEK5k2DkeW6SUQYBVe19Ga3B9GyhTX8k3CMt9JCEah13WyRnQd8GjoK6sTEvGJym6xDNvmd8yiJYSNcaYwEJsjHEUf4Yh6kAC7ki2KRvVAr3NVe1gjqK9McrwSQjtUatvydTG8Zovcr7PPUEMf3yPMgKXjZLB2QpkH63yTTYdNAnWFuv9E6b6nYRqye5XcNi436yKw5U14fXh65yK34bgYLi9328UT1huJELsJU9BRGnGUmb6GWp6c2WL5BhnzgNTSnt9TXFfEgUMzhvKzpVBxLP44hwqqBdyUhHFysCF37531PnmiESq8x1xou23xJ6FcQbc199754MkqQd7tX9CUznGzAEqHGkzn3VBoJnojsKtgYmiTYbdRsT1CU18MbYEE7WvGAvXyxxbpNzbAcc94HrnM6cqRGmwhEBroPfFghTdmzg9D

solana-verify remote submit-job --program-id 6XBGfP17P3KQAKoJb2s5M5fR4aFTXzPeuC1af2GYkvhD
--uploader <your program authority>

solana-verify build
solana program write-buffer target/deploy/verify_squads.so --with-compute-unit-price 50000 --max-sign-attempts 50

solana program set-buffer-authority Fu3k79g53ZozAj47uq1tXrFy4QbQYh7y745DDsxjtyLR --new-buffer-authority 3JG6ULvZVCrkKtSSskKNJGe8RNZGFe8Ruev9KUhxzK5K

solana-verify export-pda-tx https://github.com/solana-developers/verify-squads --program-id 6XBGfP17P3KQAKoJb2s5M5fR4aFTXzPeuC1af2GYkvhD --uploader 3JG6ULvZVCrkKtSSskKNJGe8RNZGFe8Ruev9KUhxzK5K

solana-verify remote submit-job --program-id 6XBGfP17P3KQAKoJb2s5M5fR4aFTXzPeuC1af2GYkvhD --uploader 3JG6ULvZVCrkKtSSskKNJGe8RNZGFe8Ruev9KUhxzK5K

Verification request sent with request id: b63339d2-163e-49ac-b55d-3454c1c2b5b3
Verification in progress... ⏳ [00:18:02] ✅ Process completed. (Done in 18
minutes) Program 6XBGfP17P3KQAKoJb2s5M5fR4aFTXzPeuC1af2GYkvhD has been verified.
✅ The provided GitHub build matches the on-chain hash. On Chain Hash:
96f8c3d9400258f7759408d1f6f8435b4a24d9b52f5a0340d97907e567cb8773 Executable
Hash: 96f8c3d9400258f7759408d1f6f8435b4a24d9b52f5a0340d97907e567cb8773 Repo URL:
https://github.com/Woody4618/verify-squads/tree/0fb0a2e30c15c51732c0ad5e837975a6f7bbc7ed
Check the verification status at:
https://verify.osec.io/status/6XBGfP17P3KQAKoJb2s5M5fR4aFTXzPeuC1af2GYkvhD Job
url: https://verify.osec.io/job/b63339d2-163e-49ac-b55d-3454c1c2b5b3

Verificar desde imagen docker

También puedes verificar tu programa contra una imagen docker ejecutando el siguiente comando:

solana-verify verify-from-image -e
examples/hello_world/target/deploy/hello_world.so -i
ellipsislabs/hello_world_verifiable_build:latest -p
2ZrriTQSVekoj414Ynysd48jyn4AX6ZF4TTJRqHfbJfn

Este comando carga la imagen almacenada en ellipsislabs/hello_world_verifiable_build:latest, y verifica que el hash del ejecutable en el contenedor sea el mismo que el hash del programa en cadena proporcionado al comando. Como la compilación ya fue subida a una imagen, no es necesario recompilar completamente el ejecutable, lo que puede llevar mucho tiempo.

El Dockerfile que crea la imagen ellipsislabs/hello_world_verifiable_build:latest se puede encontrar en el repositorio de Ellipsis Labs /examples/hello_world.

A continuación se muestra la salida esperada:

Verifying image: "ellipsislabs/hello_world_verifiable_build:latest", on network
"https://api.mainnet-beta.solana.com" against program ID
2ZrriTQSVekoj414Ynysd48jyn4AX6ZF4TTJRqHfbJfn Executable path in container:
"examples/hello_world/target/deploy/hello_world.so"

Executable hash:
08d91368d349c2b56c712422f6d274a1e8f1946ff2ecd1dc3efc3ebace52a760 Program hash:
08d91368d349c2b56c712422f6d274a1e8f1946ff2ecd1dc3efc3ebace52a760 Executable
matches on-chain program data ✅

Ejemplo de compilación verificada

Aquí hay un ejemplo de verificación de un programa de ejemplo con el ID FWEYpBAf9WsemQiNbAewhyESfR38GBBHLrCaU3MpEKWv utilizando el código fuente de este repositorio:

solana-verify verify-from-repo https://github.com/solana-developers/verified-program --url YOUR-RPC-URL --program-id FWEYpBAf9WsemQiNbAewhyESfR38GBBHLrCaU3MpEKWv --mount-path waffle --library-name waffle --commit-hash 5b82b86f02afbde330dff3e1847bed2d42069f4e

Por defecto, el comando verify-from-repo toma el último commit en la rama principal. También puedes definir un commit específico en caso de que quieras continuar trabajando en el repositorio usando el parámetro commit-hash: --commit-hash 5b82b86f02afbde330dff3e1847bed2d42069f4e

Finalmente, también puedes verificar directamente el programa contra la API de OtterSec:

solana-verify verify-from-repo https://github.com/solana-developers/verified-program --url YOUR-RPC-URL --remote --program-id FWEYpBAf9WsemQiNbAewhyESfR38GBBHLrCaU3MpEKWv --mount-path waffle --library-name waffle --commit-hash 5b82b86f02afbde330dff3e1847bed2d42069f4e

El comando --remote envía una solicitud de compilación a la API de OtterSec, que desencadena una compilación remota de tu programa. Una vez que la compilación está completa, el sistema verifica que el hash en cadena de tu programa coincida con el hash del artefacto de compilación generado desde tu repositorio.

Programas populares que ya están verificados

Phoenix

solana-verify verify-from-repo -um --program-id PhoeNiXZ8ByJGLkxNfZRnkUfjvmuYqLR89jjFHGqdXY https://github.com/Ellipsis-Labs/phoenix-v1

Resultado final:

Executable Program Hash from repo: 6877a5b732b3494b828a324ec846d526d962223959534dbaf4209e0da3b2d6a9
On-chain Program Hash: 6877a5b732b3494b828a324ec846d526d962223959534dbaf4209e0da3b2d6a9
Program hash matches ✅

Squads V3

solana-verify verify-from-repo https://github.com/Squads-Protocol/squads-mpl --commit-hash c95b7673d616c377a349ca424261872dfcf8b19d --program-id SMPLecH534NA9acpos4G6x7uf3LWbCAwZQE9e8ZekMu -um --library-name squads_mpl --bpf

Observa que necesitamos especificar el library-name porque el repositorio de Squads incluye múltiples programas. Usamos la bandera --bpf porque squads_mpl fue verificado previamente con Anchor.

Resultado final:

Executable Program Hash from repo: 72da599d9ee14b2a03a23ccfa6f06d53eea4a00825ad2191929cbd78fb69205c
On-chain Program Hash: 72da599d9ee14b2a03a23ccfa6f06d53eea4a00825ad2191929cbd78fb69205c
Program hash matches ✅

Drift V2

solana-verify verify-from-repo -um --program-id dRiftyHA39MWEi3m9aunc5MzRF1JYuBsbn6VPcn33UH https://github.com/drift-labs/protocol-v2 --commit-hash 110d3ff4f8ba07c178d69f9bfc7b30194fac56d6 --library-name drift

Resultado final:

Executable Program Hash from repo: e31d58edeabc3c30bf6f2aa60bfaa5e492b41ec203e9006404b463e5adee5828
On-chain Program Hash: e31d58edeabc3c30bf6f2aa60bfaa5e492b41ec203e9006404b463e5adee5828
Program hash matches ✅

Marginfi V2

solana-verify verify-from-repo -um --program-id MFv2hWf31Z9kbCa1snEPYctwafyhdvnV7FZnsebVacA https://github.com/mrgnlabs/marginfi-v2 --commit-hash d33e649e415c354cc2a1e3c49131725552d69ba0 --library-name marginfi -- --features mainnet-beta

Resultado final:

Executable Program Hash from repo: 890d68f48f96991016222b1fcbc2cc81b8ef2dcbf280c44fe378c523c108fad5
On-chain Program Hash: 890d68f48f96991016222b1fcbc2cc81b8ef2dcbf280c44fe378c523c108fad5
Program hash matches ✅

Conclusión

El uso de compilaciones verificadas en Solana asegura la integridad y confiabilidad de tus programas en la red y permite a los desarrolladores encontrar tus SDKs directamente desde Solana Explorer. Al aprovechar herramientas como Solana Verify CLI y Docker, puedes mantener compilaciones verificables y seguras que se alineen con tu código fuente. Siempre toma las precauciones necesarias para usar entornos consistentes, y considera soluciones de gobernanza para actualizaciones y despliegues seguros.

Seguridad + Descargo de responsabilidad

Aunque las compilaciones verificadas son una herramienta poderosa para asegurar la integridad de tus programas en Solana, no son completamente sin confianza en la configuración predeterminada. Las imágenes de docker son construidas y alojadas por la Fundación Solana.

Ten en cuenta que estás construyendo tu proyecto en una imagen docker descargada y que toda tu configuración se copia en esa imagen docker para la compilación, incluyendo información potencialmente sensible.

Si deseas tener una configuración completamente sin confianza, puedes construir las imágenes docker tú mismo y alojarlas en tu propia infraestructura. De esta manera puedes asegurarte de que las imágenes docker no han sido manipuladas. Puedes encontrar los scripts para crear tus propias imágenes docker en el repositorio de compilaciones verificadas y puedes hacer un fork y ejecutar las acciones de github tú mismo o validar que son correctas.

Además, para la verificación remota estás confiando en la API de OtterSec y el Explorador de Solana hasta cierto punto.

La API o el Explorador de Solana podrían mostrar información incorrecta si son comprometidos.

Si deseas tener una configuración completamente sin confianza, puedes ejecutar la API de Verify tú mismo o ejecutar la verificación del programa localmente usando el comando verify-from-repo utilizando los datos de verificación en cadena que se guardan en un PDA que se deriva de la autoridad de despliegue de los programas y el programa de verificación.

El programa de verificación es implementado por el equipo OtterSec y aún no está congelado, por lo que puede actualizarse en cualquier momento.

La Fundación Solana, OtterSec y el equipo de Ellipsis Labs no son responsables de ninguna pérdida o daño que pueda ocurrir al utilizar el proceso de compilaciones verificadas.

Security.txt para programas de Solana

Además de las compilaciones verificadas, también puedes añadir un archivo security.txt a tu programa. En el futuro, una vez implementado, el security.txt contendrá la clave pública del verificador para facilitar el acceso a los datos de verificación almacenados en el PDA de verificación. El PDA que contiene toda la información necesaria para compilar y verificar un programa se deriva de la dirección del programa y la pubkey del verificador. Por defecto, esta es la misma pubkey que compiló e implementó el programa. Pero también puede ser otra pubkey que se puede especificar en el security.txt.

La función security.txt permite a los desarrolladores integrar información de contacto y seguridad directamente en sus contratos inteligentes de Solana. Inspirado en securitytxt.org, este enfoque proporciona una forma estandarizada para que los investigadores de seguridad se pongan en contacto con los mantenedores del proyecto, incluso si solo conocen la dirección del contrato.

¿Por qué usar security.txt?

Para muchos proyectos, especialmente los más pequeños o privados, identificar a los desarrolladores solo con la dirección del contrato puede ser difícil y llevar mucho tiempo. Incorporar un archivo security.txt dentro del programa garantiza que los investigadores de seguridad puedan contactar fácilmente a las personas correctas, potencialmente previniendo explotaciones y asegurando informes de errores oportunos.

Cómo implementar security.txt

Para añadir un security.txt a tu programa de Solana, incluye los siguientes pasos:

Añade la dependencia solana-security-txt a tu Cargo.toml:

[dependencies]
solana-security-txt = "1.1.1"

Utiliza la macro security_txt! en tu contrato para definir tu información de seguridad. Puedes incluir detalles de contacto, URLs del proyecto e incluso una política de seguridad. Aquí tienes un ejemplo:

#[cfg(not(feature = "no-entrypoint"))]
use {default_env::default_env, solana_security_txt::security_txt};

#[cfg(not(feature = "no-entrypoint"))]
security_txt! {
    name: "MyProject",
    project_url: "https://myproject.com",
    contacts: "email:security@myproject.com,discord:security#1234",
    policy: "https://myproject.com/security-policy",

    // Optional Fields
    preferred_languages: "en,de",
    source_code: "https://github.com/solana-developers/solana-game-preset",
    source_revision: "5vJwnLeyjV8uNJSp1zn7VLW8GwiQbcsQbGaVSwRmkE4r",
    source_release: "",
    encryption: "",
    auditors: "Verifier pubkey: 5vJwnLeyjV8uNJSp1zn7VLW8GwiQbcsQbGaVSwRmkE4r",
    acknowledgements: "Thank you to our bug bounty hunters!"
}

Una vez que la información de security.txt está integrada en tu programa, puede ser consultada fácilmente a través de herramientas como Solana Explorer, asegurando que tus datos de contacto y seguridad estén disponibles para cualquiera que quiera reportar posibles problemas.

Mejores prácticas

• Usa enlaces: Para información que probablemente cambie (por ejemplo, detalles de contacto), se recomienda enlazar a una página web en lugar de codificarla directamente en el contrato. Esto evita la necesidad de actualizaciones frecuentes del programa.

• Verificación: Antes de implementar, verifica el formato y contenido usando la herramienta query-security-txt, que puede validar tanto programas en cadena como binarios locales:

query-security-txt target/bpfel-unknown-unknown/release/my_contract.so

Al integrar la información de contacto de seguridad directamente en tu contrato, facilitas que los investigadores se pongan en contacto contigo, fomentando una mejor seguridad y comunicación dentro del ecosistema de Solana.

Este es un ejemplo de cómo se ve security.txt en Solana Explorer

El proyecto security.txt es mantenido por Neodyme Labs